@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/workers/pi-worker-core.d.ts

@@ -1,4 +1,6 @@
 import { type ContextSnapshot, type LoopHit, type SpawnFn } from '../shared/child-process.js';
+import { type CommandKill } from '../shared/command-watchdog.js';
+export { commandCeilingForAttempt } from '../shared/command-watchdog.js';
 import { RESTART_ORDER } from './worker-kill.js';
 import { type WorkerGuardOverride, type WorkerGuardPolicy, type WorkerPolicyInputs, type WorkerProfileId } from './worker-profiles.js';
 /**
@@ -6,44 +8,48 @@ import { type WorkerGuardOverride, type WorkerGuardPolicy, type WorkerPolicyInpu
  * command could be cited from. `pi-worker-docs` (the primary), `read` and `grep`
  * (project source), and the web escalations `pi-worker-search`/`pi-worker-fetch`.
  *
- * `ls` and `find` are deliberately EXCLUDED: they return file/directory NAMES,
- * and APIS owns symbols by name only, never paths (RESEARCH_APIS_PROMPT). Bare
- * enumeration cannot verify a signature, so a worker that fabricates its section
- * from memory does not launder itself grounded by calling `ls` once. That
- * exclusion is the anti-gaming property of any gate built on this count: "one
- * trivial `ls` then fabricate the rest" leaves groundingRetrievalCount at 0.
+ * `ls` and `find` are deliberately EXCLUDED: they return file and directory
+ * NAMES, and APIS owns symbols by name only, never paths (see
+ * RESEARCH_APIS_PROMPT in prompts.ts). Bare enumeration cannot verify a
+ * signature, so a worker that fabricates its section from memory cannot launder
+ * itself grounded by calling `ls` once — "one trivial `ls` then fabricate the
+ * rest" still leaves groundingRetrievalCount at 0.
+ *
+ * The set is DERIVED from WORKER_CHANNELS (worker-channels.ts), not hand-kept.
+ * Re-exported here only so worker-channels.test.ts can assert this module hands
+ * back the same predicate.
  */
 export { isGroundingRetrieval } from './worker-channels.js';
 /**
  * Does this partial output carry ANSWER CONTENT, or is it the model clearing its
  * throat?
  *
- * Salvage originally kept the LONGEST partial, which is not the same question. On
- * the live carry arm, TASK_0020 and TASK_0021 both timed out on all three
- * attempts and salvage shipped this as the section:
+ * Keeping the LONGEST partial is not the same question, and it has an obvious
+ * failure: a preamble sentence like
  *
  *     "Now let me get more details on the specific APIs and components I need:"
  *
- * — a preamble sentence, which beats an empty string on length and carries
- * nothing. Both trials scored 2 entries and DEGRADED, against 22 and 5 for the
- * same fixtures in baseline.
+ * beats an empty string on length and carries nothing.
  *
  * A research worker's answer is a list of lines that each name something and
- * describe it. The test is therefore structural, not lexical: at least two lines
- * that look like entries — a name, then a gap, then a description. Prose wraps
- * at no particular column and does not repeat that shape.
+ * describe it. The test is therefore structural, not lexical: at least TWO lines
+ * that look like entries — a name, then a gap, then a description. Prose wraps at
+ * no particular column and does not repeat that shape; the sentence above scores
+ * zero entry lines.
  */
 export declare function hasAnswerContent(text: string): boolean;
 /**
  * Is ONE line an entry — a name, a gap, then a description — rather than prose?
  *
- * Split out of `hasAnswerContent` so the same rule can decide what a line IS,
- * not just how many of them there are. A FILES section's paths are read back
- * with it, and a scorer that used its own idea of an entry counted a preamble
- * sentence and a leaked `</tool_call>` as invented paths.
+ * Split out of `hasAnswerContent` so the same rule can decide what a line IS, not
+ * just how many of them there are — a reader of a FILES section needs the same
+ * test, and its own idea of an entry would count a preamble sentence or a leaked
+ * `</tool_call>` as one.
  *
- * Prose wraps at no particular column, so it carries no two-space gap and no
- * spaced dash; when it does, it ends in `.` or `:` and an entry does not.
+ * A leading `-`, `*`, `•` or `1.`/`1)` bullet is stripped first. What remains must
+ * hold a two-space gap or a spaced dash and must NOT end in `.` or `:`. Prose
+ * wraps at no particular column, so it carries neither; when it does carry one, it
+ * ends in punctuation and an entry does not.
  */
 export declare function isEntryLine(raw: string): boolean;
 /**
@@ -67,7 +73,7 @@ export interface RunWorkerInput {
     /** Called for each tool execution start and text-writing event inside the worker. */
     onLine?: (line: string) => void;
     /** Called when a tool call FINISHES, with its (truncatable) result — lets a caller
-     *  log tool OUTPUTS, not just the command (mx5 run 10 item 6). */
+     *  log tool OUTPUTS, not just the command. */
     onToolResult?: (result: {
         name: string;
         isError: boolean;
@@ -85,34 +91,31 @@ export interface RunWorkerInput {
      * The worker child's context window in tokens, or `'unknown'` when the
      * caller genuinely has none.
      *
-     * REQUIRED, and required for the same reason `profile` below is. This was
-     * `contextWindow?: number`, and two of the three production call sites simply
-     * did not write it: `pi-worker.ts` and `research-worker.ts`. pi's event
-     * stream carries no window (issue #16), so `noteContext` only ever saw 0, and
-     * `StallDetector`'s CONTEXT CHURN rule — gated on a positive window
-     * (`stall-detector.ts`) — could never fire for the ad-hoc worker or for any
-     * of the four research workers. Nothing was red. The optional was the whole
-     * defect: a rule that silently does not exist reads exactly like a rule that
-     * exists and did not trip.
+     * REQUIRED, and required for the same reason `profile` below is. pi's event
+     * stream carries NO window — the string `context_usage` appears nowhere in any
+     * installed @earendil-works package, and its only usage-bearing JSON event is
+     * `message_update` — so this parameter is the only source there is. Left
+     * optional, a caller that omits it leaves `noteContext` seeing 0, and
+     * `StallDetector`'s CONTEXT CHURN rule is gated on a positive window, so the
+     * rule silently does not exist. That reads exactly like a rule that exists and
+     * did not trip.
      *
-     * WHY A WORD AND NOT `0` OR `null`. Both of those are what a caller types
-     * when it has not thought about the question, and both disarm the rule
-     * silently — which is the state this replaces. `'unknown'` cannot be typed by
-     * accident, is greppable, and shows up in a diff as a decision.
+     * WHY A WORD AND NOT `0` OR `null`. Both of those are what a caller types when
+     * it has not thought about the question, and both disarm the rule silently.
+     * `'unknown'` cannot be typed by accident, is greppable, and shows up in a diff
+     * as a decision.
      *
      * Two consumers read it: the churn rule, and the caller's progress bar, which
-     * shows a bare token count without a window. Both degrade exactly as before
-     * on `'unknown'`.
+     * shows a bare token count without a window. Both degrade on `'unknown'`.
      */
     contextWindow: number | 'unknown';
     /**
      * WHICH KIND of worker child this is — the whole guard policy, in one word.
      *
-     * REQUIRED, and required on purpose. The ten guard knobs this replaces used
-     * to sit here as independent optionals, so a caller that named none of them
-     * still got a full policy and nobody could see which one. That is how the
-     * ad-hoc `pi-worker` tool came to run the strictest wall clock of the three
-     * children without anyone deciding it should. See worker-profiles.ts.
+     * REQUIRED, and required on purpose. As independent optionals, a caller that
+     * named none of the guard knobs still got a full policy and nobody could see
+     * which one — so a child can end up running the strictest wall clock of the
+     * three without anyone deciding it should. See worker-profiles.ts.
      */
     profile: WorkerProfileId;
     /**
@@ -121,10 +124,11 @@ export interface RunWorkerInput {
      */
     policyInputs?: WorkerPolicyInputs;
     /**
-     * Whole guard rows laid over the profile's. TESTS AND A/B HARNESSES ONLY —
-     * an override at a production call site is the hand-picked subset this
-     * design exists to stop, and `worker-profiles.test.ts` fails the build if
-     * one appears under src/ outside a test.
+     * Whole guard rows laid over the profile's. TESTS AND HARNESSES ONLY — an
+     * override at a production call site is the hand-picked subset this design
+     * exists to stop. `worker-profiles.test.ts` enforces it: its "no production
+     * source file passes an `override` to runWorker" test scans src/ for a leading
+     * `override:` and fails on any hit.
      */
     override?: WorkerGuardOverride;
     /**
@@ -133,9 +137,9 @@ export interface RunWorkerInput {
      *
      * WHY: asserting that a profile RESOLVES correctly proves nothing about
      * whether runWorker then READS it correctly — a rewiring that turns "0 means
-     * off" into "0 means on" leaves every profile assertion green. This hook is
-     * what lets a caller's own test (gate-child.test.ts) drive the REAL call
-     * site and check the REAL policy, instead of re-typing the table.
+     * off" into "0 means on" leaves every profile assertion green. This hook lets
+     * a test drive the REAL call site and read back the REAL policy instead of
+     * re-typing the table; worker-profiles.test.ts is where those assertions live.
      */
     onPolicy?: (policy: WorkerGuardPolicy) => void;
     /** Backoff sleep, injectable so tests don't wait out the real delays. */
@@ -168,12 +172,10 @@ export interface RunWorkerInput {
      *
      * WHY: every restart branch below throws away a whole attempt's wall clock
      * along with its text, and `waitMs`/`workMs` describe the FINAL attempt only.
-     * With no hook here those attempts were structurally invisible: mx5 run 18
-     * burned 30 wall-clock timeouts / 120 minutes of compute that appeared in no
-     * log and no timing widget, and 21 of the 23 affected workers reported
-     * `exit=0` — clean successes as far as the run could tell. The discrepancy
-     * was only recoverable by subtracting reported wait+work from the timestamps
-     * of the `start` and `done` lines around it.
+     * With no hook here a discarded attempt is structurally invisible — the worker
+     * still returns `exitCode` 0 and reads as a clean success, and the lost time is
+     * recoverable only by subtracting the reported wait+work from the timestamps
+     * around the call.
      */
     onRestart?: (restart: WorkerRestart) => void;
 }
@@ -200,13 +202,9 @@ export interface WorkerRestart {
      * thrown away.
      *
      * Recorded whatever `carryForward` says, because the DISCARD is the thing a
-     * reader cannot otherwise see. A restart line reported how long an attempt
-     * ran and why it died, and never what died with it — so "the guards worked
-     * and the run still returned 52 characters" and "the guards worked and the
-     * run threw away a finished answer" print identically. Measured on the
-     * ad-hoc `pi-worker` corpus: T024 lost an attempt to a dropped model socket
-     * at 275s and returned 52 chars over 620s; nothing in the run said whether
-     * those 275s held anything.
+     * reader cannot otherwise see. Without it, "the guards worked and the run
+     * returned almost nothing" and "the guards worked and the run threw away a
+     * finished answer" print identically.
      *
      * It is an OBSERVATION, not a decision: harvesting into `salvage` is still
      * gated on the profile, and this number changes no behaviour.
@@ -222,9 +220,9 @@ export interface RunWorkerResult {
      * The provider-reported cause when the model turn itself failed (disconnect,
      * fetch failed, 5xx after pi's own retries): pi delivers it as an assistant
      * message with stopReason "error" and EMPTY text, exit code 0. Phase children
-     * have always surfaced this (child-runner.ts) — research workers did not, so a
-     * swallowed provider error reached the caller as an indistinguishable empty
-     * answer and was reported as the useless "produced no output" (issue #10).
+     * surface this through child-runner.ts; without it a swallowed provider error
+     * reaches the caller as an indistinguishable empty answer and gets reported as
+     * the useless "produced no output".
      * Only meaningful when `text` is empty: a turn that produced text after pi
      * recovered is a success, and the first-error capture must not relabel it.
      */
@@ -341,28 +339,6 @@ export interface RunWorkerResult {
         idleMs: number;
     };
 }
-/**
- * The per-command ceiling for attempt N, halving each time a hang recurs.
- *
- * The first attempt gets the full configured ceiling — a genuinely slow build or
- * test suite deserves it. But every hang-caused restart carries
- * commandTimeoutHint, which tells the model in as many words to bound its
- * command; a SECOND hang means it ignored an explicit instruction, and a third
- * means it ignored it twice. Giving a non-complying child the full ceiling again
- * would put the worst case at 3 × 15 min = 45 minutes of dead time, resting
- * entirely on the model obeying prose. Halving bounds it at ~26 min while
- * costing a complying child nothing.
- *
- * `priorHangs` counts watchdog kills specifically, NOT total restarts — the
- * restart budget is shared with loop kills, and a child restarted for LOOPING
- * never received the bound-your-command hint, so its first hang still deserves
- * the full ceiling. Only a hang after a hang is defiance.
- *
- * Floored at 30s so repeated halving cannot shrink the ceiling to something no
- * real command could finish inside — but never ABOVE the configured ceiling
- * itself, or a caller asking for 10s would silently get 30.
- */
-export declare function commandCeilingForAttempt(baseMs: number, priorHangs: number): number;
 /**
  * Everything the restart ladder reads about one finished attempt, plus the
  * budgets it draws on. Assembled once per attempt so the rules below can be
@@ -377,7 +353,8 @@ interface RestartState {
     timedOut: boolean;
     modelError?: string;
     leaked: string | null;
-    /** The cap this attempt actually died against — the SCALE arm moves it. */
+    /** The cap this attempt actually died against, not the configured one:
+     *  `extend`/`progress` can push the deadline out during the attempt. */
     effectiveCapMs: number;
     /** The child's tool string, which decides whether its edits can persist. */
     tools: string;
@@ -440,12 +417,4 @@ interface RestartRule {
  * becoming visible in `restarts`.
  */
 export declare const RESTART_RULES: readonly RestartRule[];
-/** What the command watchdog recorded when it killed an attempt. */
-interface CommandKill {
-    toolName: string;
-    timeoutMs: number;
-    /** The command line itself, when the tool carried one — quoted into the hint
-     *  so the fresh child knows which call it must not repeat unbounded. */
-    detail?: string;
-}
 export declare function runWorker(input: RunWorkerInput): Promise<RunWorkerResult>;