@namzu/sdk 42.0.0 → 42.0.2

package/dist/runtime/query/iteration/outstanding-work.js

@@ -0,0 +1,365 @@
+import { NAMZU } from '../../../constants/telemetry/index.js';
+import { formatCompletionNotification } from '../../../scheduler/completion-inbox.js';
+import { DELEGATION_TIMEOUT_MS } from '../../../tools/coordinator/index.js';
+import { createRuntimeContextMessage } from '../../../types/message/index.js';
+import { readPositiveIntEnv } from '../../../utils/env.js';
+import { formatJobNote } from '../steering.js';
+/**
+ * The run's settle points: holding open for work that has not finished, and
+ * delivering what arrived.
+ *
+ * Two kinds of work qualify — a delegated task the `CompletionInbox` is still
+ * expecting, and a background job the model told `wait_for_job` it is waiting
+ * on — and both are raced together, because a run has one settle point and one
+ * grace period to spend at it.
+ *
+ * Everything here reads the iteration context rather than capturing it, and
+ * the one thing it cannot read off that context — how this run drains its
+ * inbound queue — arrives as an explicit `deliverInbound` input, because the
+ * recording of operator intent that goes with it belongs to the orchestrator.
+ * `holdForOutstandingWork` is a generator and is reached with `yield*`: its
+ * one event must land at the position it landed at when it lived on the class.
+ */
+/**
+ * The share of a run's REMAINING time a settle-hold may take.
+ *
+ * The rule is borrowed from `AGENT_MANAGER_DEFAULTS.maxBudgetFraction`, which
+ * gives a spawned child at most half of what its parent has left: one
+ * sub-activity may take a share of the remainder, never the remainder. The
+ * value is written out here rather than imported, because that field is a
+ * host-tunable knob about TOKEN allocation and coupling the two would let a
+ * host lowering one silently change the other.
+ *
+ * Half, specifically, because the hold is not the last thing the run does.
+ * Its whole purpose is to put a worker's result where the model can read it,
+ * and reading it costs a turn. A hold that spent everything remaining would
+ * deliver a notification into a run with no turn left to act on it — the same
+ * "the result exists and the model is never told" failure this mechanism was
+ * built to close, wearing a different costume.
+ */
+const SETTLE_GRACE_FRACTION = 0.5;
+/**
+ * How long a finishing run waits for a background worker it launched.
+ *
+ * Derived from the run rather than fixed, because a constant is wrong in both
+ * directions at once. The 120 seconds this replaces held a run configured for
+ * a twenty-second timeout open for 120,267 ms — six times its own budget, and
+ * unreachable by the guard, which only checks between iterations — while on an
+ * hour-long run it abandoned workers measured at 4m21s, 5m58s and 8m04s, all
+ * of them well inside the hour the delegation tools themselves declare.
+ *
+ * **Bounded by construction, and against the right boundary.** The input is
+ * time-to-FINALIZE, not time-to-deadline (see
+ * `GuardCoordinator.remainingBeforeFinalizeMs`). Measuring to the deadline was
+ * the first attempt and it was wrong in a way that looked safe: a hold cannot
+ * outlive the deadline either way, but half of the time-to-deadline started
+ * just under the warning threshold ends at 95% of the budget — so the slice
+ * that exists for the run to produce a closing answer is half spent waiting
+ * for the result that answer was supposed to use. Against the finalize point
+ * the hold cannot reach the reserve at all, which is what makes the guard's
+ * inability to interrupt a hold a non-issue rather than a smaller issue.
+ *
+ * **The floor of zero is a decision, not a clamp artefact.** A run with no
+ * time left before it must start finishing has no turn in which to read a
+ * notification, so waiting could only delay a stop that is already due.
+ * Nothing is lost by it: `CompletionInbox.waitForArrival` returns before it
+ * looks at its timer when a completion is already in hand, so a zero grace
+ * still delivers everything that has arrived. No minimum is invented on top,
+ * because zero is exactly what a run past the threshold should wait — and
+ * reading the remainder at hold time rather than trusting `forceFinalize`,
+ * which is sampled at the top of the iteration, is what makes a long iteration
+ * that crossed the line in between compute it.
+ *
+ * **The ceiling is the longest anything in this subsystem waits for a
+ * delegated worker.** It binds only for a host whose run timeout exceeds
+ * roughly two and a quarter hours; below that the fraction is smaller.
+ */
+export function settleGraceMs(remainingBeforeFinalizeMs) {
+    return Math.min(Math.floor(remainingBeforeFinalizeMs * SETTLE_GRACE_FRACTION), DELEGATION_TIMEOUT_MS);
+}
+/**
+ * The ceiling on the job half of that grace, in milliseconds.
+ *
+ * `DELEGATION_TIMEOUT_MS` is the wrong ceiling for a shell job, and the gap
+ * only opens where it matters most: a run with no `timeoutMs` — the CLI's
+ * shipping default, `No run deadline by default` — has infinite time before
+ * it must start finishing, so `settleGraceMs` returns the ceiling flat. For a
+ * delegated task that is sound, because the hour is the longest the task
+ * itself may live: the hold cannot outlast the work. A background job has no
+ * such bound. `tail -f`, a watcher and a dev server all outlive any hold, so
+ * the same arithmetic parks an interactive session for an hour on a job that
+ * was never going to exit.
+ *
+ * So the job leg gets its own bound, and it is sized to what the wait buys
+ * rather than to how long a job may live: a turn in which to use the exit.
+ * A model that already waited its `wait_for_job` bound out and saw nothing is
+ * not usually two minutes from an exit, and the run ending is not the news
+ * being lost — with no run in flight the session announces the exit itself
+ * (`docs/cli/background-jobs.md`, *Learning that it ended*), which is the
+ * cheaper of the two places to hear it.
+ */
+const DEFAULT_JOB_HOLD_MAX_MS = 2 * 60 * 1000;
+/**
+ * The same share of the run, under {@link DEFAULT_JOB_HOLD_MAX_MS}.
+ *
+ * `NAMZU_JOB_HOLD_MAX_MS` overrides the ceiling for a host that wants a
+ * longer or shorter park, the way `NAMZU_JOB_WAIT_TIMEOUT_MS` overrides
+ * `wait_for_job`'s own bound — and it is the same parse, so a value that is
+ * not a positive whole number of milliseconds leaves the default standing
+ * rather than holding a run for `NaN`. Called here rather than at module
+ * load, because a host that sets it after import is not ignored.
+ */
+export function awaitedJobGraceMs(remainingBeforeFinalizeMs) {
+    const ceiling = readPositiveIntEnv('NAMZU_JOB_HOLD_MAX_MS', DEFAULT_JOB_HOLD_MAX_MS);
+    return Math.min(settleGraceMs(remainingBeforeFinalizeMs), ceiling);
+}
+/**
+ * Hold the run open for work that has not finished, and deliver it.
+ *
+ * Returns whether a completion, a job exit or an operator message entered
+ * the transcript — the caller continues on `true`, so the model gets a turn
+ * to respond. That turn is the entire justification for waiting, which
+ * is why only the exits that can still take one call this.
+ *
+ * Two kinds of work qualify and they are raced together, because a run has
+ * one settle point and one grace period to spend at it:
+ *
+ *  - a delegated task the `CompletionInbox` is still expecting;
+ *  - a background job the model told `wait_for_job` it is waiting on.
+ *
+ * The job half is deliberately narrow. Intent comes from the wait and from
+ * nothing else — a dev server the model started and never waited on is
+ * running because somebody wanted it running, and a hold for it would add
+ * the grace period to the end of every turn for the rest of the session.
+ *
+ * Each leg is opened only when it has something pending: both
+ * `waitForArrival` implementations resolve immediately when their own side
+ * is idle, so racing an idle one would end the hold before it began.
+ *
+ * Bounded by `settleGraceMs` and by `maxIterations`, so work that never
+ * finishes cannot keep the run open. On a run with a deadline the grace is
+ * a share of what is LEFT of it rather than a fresh allowance, so a
+ * `wait_for_job` call that already spent minutes has shortened this hold
+ * by the same minutes. On a run without one — the CLI's default — there is
+ * no remainder to take a share of, and the job leg's own ceiling
+ * (`awaitedJobGraceMs`) is what keeps a timed-out wait from being followed
+ * by an hour of silence.
+ */
+export async function* holdForOutstandingWork(ctx, iterationNum, hasToolCalls, deliverInbound) {
+    const inbox = ctx.completionInbox?.hasPendingWork ? ctx.completionInbox : undefined;
+    const jobs = ctx.awaitedJobs?.hasPendingWork ? ctx.awaitedJobs : undefined;
+    if (!inbox && !jobs)
+        return false;
+    // Read HERE rather than from `forceFinalize`, which was sampled at the
+    // top of the iteration: one that has since crossed the finalize point
+    // must not open a wait against a reserve it has already entered.
+    const remainingMs = ctx.guard.remainingBeforeFinalizeMs();
+    // One deadline for the race, and it is the LONGEST ceiling any pending
+    // leg justifies. A leg resolving on its own timer ends the whole race,
+    // so handing the job leg its shorter ceiling while a task was also
+    // outstanding would cut the task's hold down to the job's — a run
+    // walking away from a worker it had time for, because a job happened
+    // to be running. A job therefore never shortens a wait, and it never
+    // lengthens one either: where a task is outstanding too, that is how
+    // long this run was waiting anyway.
+    const graceMs = inbox ? settleGraceMs(remainingMs) : awaitedJobGraceMs(remainingMs);
+    ctx.log.info('Holding the run open for outstanding work', {
+        [NAMZU.RUN_ID]: ctx.runMgr.id,
+        [NAMZU.ITERATION]: iterationNum,
+        'namzu.runtime.grace_ms': graceMs,
+        'namzu.runtime.awaited_jobs': jobs?.outstandingJobIds ?? [],
+    });
+    // User input releases this wait without cancelling any child. Both waits
+    // share a disposable signal so the losing arrival listener cannot leak.
+    const waiting = new AbortController();
+    const runSignal = ctx.abortController.signal;
+    const cancelWait = () => waiting.abort(runSignal.reason);
+    runSignal.addEventListener('abort', cancelWait, { once: true });
+    if (runSignal.aborted)
+        cancelWait();
+    try {
+        await Promise.race([
+            ...(inbox ? [inbox.waitForArrival(graceMs, waiting.signal)] : []),
+            ...(jobs ? [jobs.waitForArrival(graceMs, waiting.signal)] : []),
+            ...(ctx.waitForInbound ? [ctx.waitForInbound(waiting.signal)] : []),
+        ]);
+    }
+    catch (error) {
+        if (!runSignal.aborted)
+            throw error;
+    }
+    finally {
+        waiting.abort();
+        runSignal.removeEventListener('abort', cancelWait);
+    }
+    runSignal.throwIfAborted();
+    const arrived = ctx.completionInbox?.drain() ?? [];
+    if (arrived.length > 0) {
+        ctx.runMgr.pushMessage(createRuntimeContextMessage(formatCompletionNotification(arrived), 'task-completion'));
+    }
+    const exited = deliverAwaitedJobExits(ctx);
+    const inbound = deliverInbound();
+    if (arrived.length === 0 && !exited && inbound === 0)
+        return false;
+    await ctx.emitEvent({
+        type: 'iteration_completed',
+        runId: ctx.runMgr.id,
+        iteration: iterationNum,
+        hasToolCalls,
+    });
+    yield* ctx.drainPending();
+    return true;
+}
+/**
+ * Put the job exits this hold was waiting for in front of the model.
+ *
+ * Through `jobNotices`, which is the channel a job exit already travels on
+ * — `attachNotice` rides it out on the next tool result — rather than a
+ * second one built for this path. A turn that called no tools has no such
+ * result, so the queued text becomes a `runtime-context` message instead,
+ * exactly as `deliverInbound` does for steering that found no tool result
+ * to attach to.
+ *
+ * That drain is also what keeps one exit from being delivered twice: the
+ * channel hands its text over once, so an exit already attached to a tool
+ * result earlier in the turn leaves nothing here — and the record of it
+ * went with that delivery, so this returns `false` rather than buying a
+ * turn to re-read what the model has read.
+ *
+ * `takeDelivery` is what pairs the two. Taking the exits first and then
+ * finding no notice would discard them, which is the one way this path
+ * can lose an exit outright; neither is taken unless both are there.
+ *
+ * The channel is not per-job, so the text taken here can include a notice
+ * for a job nobody awaited that ended while the hold was open. Delivering
+ * it is right — it is unread either way, and the alternative is stranding
+ * it — but it is not a reason to WAIT, which is why what opens this hold
+ * is `AwaitedJobs`, and the two are asked separately.
+ */
+export function deliverAwaitedJobExits(ctx) {
+    const delivered = ctx.awaitedJobs?.takeDelivery(() => ctx.jobNotices?.drain());
+    if (!delivered)
+        return false;
+    ctx.log.info('Delivering a background job exit the run held open for', {
+        [NAMZU.RUN_ID]: ctx.runMgr.id,
+        'namzu.runtime.jobs': delivered.exits.map((job) => job.id),
+    });
+    ctx.runMgr.pushMessage(createRuntimeContextMessage(formatJobNote(delivered.text), 'job-exit'));
+    return true;
+}
+/**
+ * Account for outstanding work on the way out: deliver what arrived, and
+ * say what did not.
+ *
+ * A run that ends with a worker outstanding must not leave the impression
+ * that the worker's result was delivered. There are exactly two honest
+ * outcomes and this does both:
+ *
+ *  - **What has already arrived is delivered.** It makes no false claim,
+ *    and dropping it is pure loss — the message rides out on
+ *    `Run.messages`, so a host reads it and the next turn of a continued
+ *    thread starts with it. This does NOT wait: a hold buys the model a
+ *    turn in which to USE a result, and on an exit whose answer is already
+ *    decided there is no such turn, so waiting would delay a settled answer
+ *    to append text this run will not read. The bounded hold stays where it
+ *    was, on the exits that do have a turn left.
+ *  - **What is still running is NAMED, not cancelled.** Giving up on a wait
+ *    is a statement about the waiter, not about the work — the rule
+ *    `wait-with-idle-bound.ts` already states for the same subsystem — and
+ *    "the parent answered early" is a weaker warrant for killing a child
+ *    than "the clock ran out", not a stronger one. Killing a worker that
+ *    may be mid-write is a policy only the host can judge, and it has
+ *    `cancel_task` and the run controller to judge it with.
+ */
+export function settleOutstandingWork(ctx) {
+    deliverArrivedCompletions(ctx);
+    deliverArrivedJobExits(ctx);
+    recordAbandonedWork(ctx);
+}
+/** Work this run walked away from. See {@link settleOutstandingWork}. */
+export function recordAbandonedWork(ctx) {
+    const abandoned = ctx.completionInbox?.outstandingTaskIds ?? [];
+    if (abandoned.length > 0) {
+        ctx.log.warn('Run ended with delegated work still running', {
+            [NAMZU.RUN_ID]: ctx.runMgr.id,
+            'namzu.runtime.tasks': abandoned,
+        });
+        ctx.runMgr.setAbandonedTaskIds(abandoned);
+    }
+    // The same statement for a job the model was waiting on when the grace
+    // ran out. Only awaited ones: a job nobody waited for was never work
+    // this run was holding, so naming it would report an abandonment that
+    // did not happen.
+    const abandonedJobs = ctx.awaitedJobs?.outstandingJobIds ?? [];
+    if (abandonedJobs.length === 0)
+        return;
+    ctx.log.warn('Run ended with an awaited background job still running', {
+        [NAMZU.RUN_ID]: ctx.runMgr.id,
+        'namzu.runtime.jobs': abandonedJobs,
+    });
+    ctx.runMgr.setAbandonedJobIds(abandonedJobs);
+}
+export function deliverArrivedCompletions(ctx) {
+    const unheard = ctx.completionInbox?.drain() ?? [];
+    if (unheard.length === 0)
+        return;
+    // Fix the run's answer BEFORE appending anything after it.
+    //
+    // `RunPersistence.resolveResult` walks the message tail backwards and
+    // stops at the first non-assistant message, and it runs at
+    // `markCompleted` — which is AFTER this. So a notification appended
+    // after the final assistant turn makes the run's own answer
+    // unreachable. Measured, on a run whose model had just said "THIS IS
+    // THE RUN ANSWER.": `run.result` came back `undefined`. That trades a
+    // lost worker result for a lost RUN result, which is strictly worse
+    // than the defect this delivery exists to fix.
+    //
+    // Materialising resolves it while the tail is still the assistant's;
+    // pinning it means the later re-resolution cannot undo the fix. Only
+    // when there is something to pin: on the cancelled and thrown paths
+    // there may be no answer, and pinning an empty string there would
+    // suppress whatever the error path assembles.
+    const answer = ctx.runMgr.materializeResult();
+    if (answer.length > 0)
+        ctx.runMgr.setResult(answer);
+    ctx.log.info('Delivering task completions the run would have settled over', {
+        [NAMZU.RUN_ID]: ctx.runMgr.id,
+        'namzu.runtime.tasks': unheard.map((h) => h.taskId),
+    });
+    ctx.runMgr.pushMessage(createRuntimeContextMessage(formatCompletionNotification(unheard), 'task-completion'));
+}
+/**
+ * The job half of {@link deliverArrivedCompletions}: an exit that arrived
+ * too late to earn a turn is still delivered on the way out.
+ *
+ * The window this closes is one tick wide and it is nobody else's. An
+ * awaited job that exits between the hold's grace expiring and the run
+ * settling was never delivered — the hold had already looked — and is no
+ * longer named either, because the exit took it off the outstanding list
+ * on its way past, so `abandonedJobIds` would be lying to claim it. The
+ * host's own listener is no help: the CLI queues an exit for the next
+ * turn only when no run is in flight, and this one is still in flight.
+ * Delivered here it reaches `Run.messages`, so the transcript has it and
+ * a continued thread opens with it.
+ *
+ * Before `recordAbandonedWork`, which then reports only what is still
+ * running, and after `deliverArrivedCompletions`, so the two appended
+ * messages land in the order the work finished in.
+ */
+export function deliverArrivedJobExits(ctx) {
+    const delivered = ctx.awaitedJobs?.takeDelivery(() => ctx.jobNotices?.drain());
+    if (!delivered)
+        return;
+    // Fix the run's answer BEFORE appending anything after it — the same
+    // `resolveResult` tail walk `deliverArrivedCompletions` explains just
+    // above, and the same guard against pinning an empty one.
+    const answer = ctx.runMgr.materializeResult();
+    if (answer.length > 0)
+        ctx.runMgr.setResult(answer);
+    ctx.log.info('Delivering a background job exit the run would have settled over', {
+        [NAMZU.RUN_ID]: ctx.runMgr.id,
+        'namzu.runtime.jobs': delivered.exits.map((job) => job.id),
+    });
+    ctx.runMgr.pushMessage(createRuntimeContextMessage(formatJobNote(delivered.text), 'job-exit'));
+}
+//# sourceMappingURL=outstanding-work.js.map

package/dist/runtime/query/iteration/outstanding-work.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outstanding-work.js","sourceRoot":"","sources":["../../../../src/runtime/query/iteration/outstanding-work.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,uCAAuC,CAAA;AAC7D,OAAO,EAAE,4BAA4B,EAAE,MAAM,wCAAwC,CAAA;AACrF,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAA;AAC3E,OAAO,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAA;AAE7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAG9C;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,qBAAqB,GAAG,GAAG,CAAA;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,aAAa,CAAC,yBAAiC;IAC9D,OAAO,IAAI,CAAC,GAAG,CACd,IAAI,CAAC,KAAK,CAAC,yBAAyB,GAAG,qBAAqB,CAAC,EAC7D,qBAAqB,CACrB,CAAA;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,uBAAuB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA;AAE7C;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,yBAAiC;IAClE,MAAM,OAAO,GAAG,kBAAkB,CAAC,uBAAuB,EAAE,uBAAuB,CAAC,CAAA;IACpF,OAAO,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC,CAAA;AACnE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,sBAAsB,CAC5C,GAAqB,EACrB,YAAoB,EACpB,YAAqB,EACrB,cAA4B;IAE5B,MAAM,KAAK,GAAG,GAAG,CAAC,eAAe,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAA;IACnF,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAA;IAC1E,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAA;IAEjC,uEAAuE;IACvE,sEAAsE;IACtE,iEAAiE;IACjE,MAAM,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,yBAAyB,EAAE,CAAA;IACzD,uEAAuE;IACvE,uEAAuE;IACvE,mEAAmE;IACnE,kEAAkE;IAClE,qEAAqE;IACrE,qEAAqE;IACrE,qEAAqE;IACrE,oCAAoC;IACpC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAA;IACnF,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,2CAA2C,EAAE;QACzD,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE;QAC7B,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,YAAY;QAC/B,wBAAwB,EAAE,OAAO;QACjC,4BAA4B,EAAE,IAAI,EAAE,iBAAiB,IAAI,EAAE;KAC3D,CAAC,CAAA;IACF,yEAAyE;IACzE,wEAAwE;IACxE,MAAM,OAAO,GAAG,IAAI,eAAe,EAAE,CAAA;IACrC,MAAM,SAAS,GAAG,GAAG,CAAC,eAAe,CAAC,MAAM,CAAA;IAC5C,MAAM,UAAU,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;IACxD,SAAS,CAAC,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAC/D,IAAI,SAAS,CAAC,OAAO;QAAE,UAAU,EAAE,CAAA;IACnC,IAAI,CAAC;QACJ,MAAM,OAAO,CAAC,IAAI,CAAC;YAClB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACjE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/D,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SACnE,CAAC,CAAA;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,CAAC,SAAS,CAAC,OAAO;YAAE,MAAM,KAAK,CAAA;IACpC,CAAC;YAAS,CAAC;QACV,OAAO,CAAC,KAAK,EAAE,CAAA;QACf,SAAS,CAAC,mBAAmB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAA;IACnD,CAAC;IACD,SAAS,CAAC,cAAc,EAAE,CAAA;IAE1B,MAAM,OAAO,GAAG,GAAG,CAAC,eAAe,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IAClD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,GAAG,CAAC,MAAM,CAAC,WAAW,CACrB,2BAA2B,CAAC,4BAA4B,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAC,CACrF,CAAA;IACF,CAAC;IACD,MAAM,MAAM,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAA;IAC1C,MAAM,OAAO,GAAG,cAAc,EAAE,CAAA;IAChC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,IAAI,OAAO,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAClE,MAAM,GAAG,CAAC,SAAS,CAAC;QACnB,IAAI,EAAE,qBAAqB;QAC3B,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE;QACpB,SAAS,EAAE,YAAY;QACvB,YAAY;KACZ,CAAC,CAAA;IACF,KAAK,CAAC,CAAC,GAAG,CAAC,YAAY,EAAE,CAAA;IACzB,OAAO,IAAI,CAAA;AACZ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAqB;IAC3D,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,EAAE,YAAY,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC,CAAA;IAC9E,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAA;IAE5B,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,wDAAwD,EAAE;QACtE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE;QAC7B,oBAAoB,EAAE,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;KAC1D,CAAC,CAAA;IACF,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,2BAA2B,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC,CAAA;IAC9F,OAAO,IAAI,CAAA;AACZ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAqB;IAC1D,yBAAyB,CAAC,GAAG,CAAC,CAAA;IAC9B,sBAAsB,CAAC,GAAG,CAAC,CAAA;IAC3B,mBAAmB,CAAC,GAAG,CAAC,CAAA;AACzB,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,mBAAmB,CAAC,GAAqB;IACxD,MAAM,SAAS,GAAG,GAAG,CAAC,eAAe,EAAE,kBAAkB,IAAI,EAAE,CAAA;IAC/D,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,6CAA6C,EAAE;YAC3D,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE;YAC7B,qBAAqB,EAAE,SAAS;SAChC,CAAC,CAAA;QACF,GAAG,CAAC,MAAM,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAA;IAC1C,CAAC;IAED,uEAAuE;IACvE,qEAAqE;IACrE,sEAAsE;IACtE,kBAAkB;IAClB,MAAM,aAAa,GAAG,GAAG,CAAC,WAAW,EAAE,iBAAiB,IAAI,EAAE,CAAA;IAC9D,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC;QAAE,OAAM;IAEtC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,wDAAwD,EAAE;QACtE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE;QAC7B,oBAAoB,EAAE,aAAa;KACnC,CAAC,CAAA;IACF,GAAG,CAAC,MAAM,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAA;AAC7C,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,GAAqB;IAC9D,MAAM,OAAO,GAAG,GAAG,CAAC,eAAe,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IAClD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAM;IAEhC,2DAA2D;IAC3D,EAAE;IACF,sEAAsE;IACtE,2DAA2D;IAC3D,oEAAoE;IACpE,4DAA4D;IAC5D,qEAAqE;IACrE,sEAAsE;IACtE,oEAAoE;IACpE,+CAA+C;IAC/C,EAAE;IACF,qEAAqE;IACrE,qEAAqE;IACrE,oEAAoE;IACpE,kEAAkE;IAClE,8CAA8C;IAC9C,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAA;IAC7C,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;IAEnD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,6DAA6D,EAAE;QAC3E,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE;QAC7B,qBAAqB,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;KACnD,CAAC,CAAA;IACF,GAAG,CAAC,MAAM,CAAC,WAAW,CACrB,2BAA2B,CAAC,4BAA4B,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAC,CACrF,CAAA;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAqB;IAC3D,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,EAAE,YAAY,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC,CAAA;IAC9E,IAAI,CAAC,SAAS;QAAE,OAAM;IAEtB,qEAAqE;IACrE,sEAAsE;IACtE,0DAA0D;IAC1D,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAA;IAC7C,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;IAEnD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,kEAAkE,EAAE;QAChF,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE;QAC7B,oBAAoB,EAAE,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;KAC1D,CAAC,CAAA;IACF,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,2BAA2B,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC,CAAA;AAC/F,CAAC"}

package/dist/runtime/query/iteration/phases/plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/query/iteration/phases/plan.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAA;AAC9D,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,WAAW,EAAsB,MAAM,cAAc,CAAA;AAE1F,wBAAuB,WAAW,CAAC,GAAG,EAAE,gBAAgB,GAAG,cAAc,CAAC,QAAQ,EAAE,WAAW,CAAC,CA2C/F"}
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/query/iteration/phases/plan.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAA;AAC9D,OAAO,EACN,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAGhB,MAAM,cAAc,CAAA;AAErB,wBAAuB,WAAW,CAAC,GAAG,EAAE,gBAAgB,GAAG,cAAc,CAAC,QAAQ,EAAE,WAAW,CAAC,CAsD/F"}

package/dist/runtime/query/iteration/phases/plan.js

@@ -1,4 +1,4 @@
-import { handleHITLDecision } from './context.js';
+import { awaitDecisionOrAbort, handleHITLDecision, } from './context.js';
 export async function* runPlanGate(ctx) {
     if (!ctx.planManager.active || ctx.planManager.active.status !== 'ready') {
         return 'continue';
@@ -33,8 +33,19 @@ export async function* runPlanGate(ctx) {
     // Record the park BEFORE awaiting it. A process that dies while a human
     // is reading the plan otherwise leaves nothing behind saying the plan
     // was ever put up for approval.
+    //
+    // The park stays eager — `awaitDecisionDurably` records only after
+    // `PARK_RECORD_DELAY_MS`, which is the right trade for a gate that runs
+    // on every iteration and the wrong one for a gate that runs once and is
+    // read by a human. Only the AWAIT below is raced.
     await ctx.checkpointMgr.park(planCheckpoint, request);
-    const planDecision = await ctx.resumeHandler(request);
+    // Raced against the run's abort signal, like every other park. A bare
+    // `await ctx.resumeHandler(request)` here meant a Stop did nothing until
+    // the host answered: `runPlanGate` runs in the iteration loop rather than
+    // inside a tool call, so nothing downstream bounded the wait. A Stop now
+    // resolves the park as `abort`, which `handleHITLDecision` turns into
+    // `setStopReason('cancelled') + markCancelled + stop`.
+    const planDecision = await awaitDecisionOrAbort(ctx, request);
     await ctx.checkpointMgr.unpark(planCheckpoint.id, planDecision);
     return yield* handleHITLDecision(ctx, planDecision, planCheckpoint.id, 'plan_gate');
 }

package/dist/runtime/query/iteration/phases/plan.js.map

@@ -1 +1 @@
-{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../../../src/runtime/query/iteration/phases/plan.ts"],"names":[],"mappings":"AAEA,OAAO,EAA2C,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAE1F,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,WAAW,CAAC,GAAqB;IACvD,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,IAAI,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;QAC1E,OAAO,UAAU,CAAA;IAClB,CAAC;IAED,MAAM,cAAc,GAAG,MAAM,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IAEpE,MAAM,GAAG,CAAC,SAAS,CAAC;QACnB,IAAI,EAAE,oBAAoB;QAC1B,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE;QACpB,YAAY,EAAE,cAAc,CAAC,EAAE;QAC/B,SAAS,EAAE,CAAC;KACZ,CAAC,CAAA;IACF,KAAK,CAAC,CAAC,GAAG,CAAC,YAAY,EAAE,CAAA;IAEzB,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,CAAC,MAAM,CAAA;IACnC,MAAM,OAAO,GAAwB;QACpC,IAAI,EAAE,eAAe;QACrB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE;QACpB,YAAY,EAAE,cAAc,CAAC,EAAE;QAC/B,IAAI,EAAE;YACL,MAAM,EAAE,IAAI,CAAC,EAAE;YACf,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC7B,EAAE,EAAE,CAAC,CAAC,EAAE;gBACR,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,QAAQ,EAAE,CAAC,CAAC,QAAQ;gBACpB,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,SAAS,EAAE,CAAC,CAAC,SAAS;gBACtB,KAAK,EAAE,CAAC,CAAC,KAAK;aACd,CAAC,CAAC;YACH,OAAO,EAAE,IAAI,CAAC,OAAO;SACrB;KACD,CAAA;IAED,wEAAwE;IACxE,sEAAsE;IACtE,gCAAgC;IAChC,MAAM,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAA;IACrD,MAAM,YAAY,GAAG,MAAM,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;IACrD,MAAM,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,EAAE,YAAY,CAAC,CAAA;IAE/D,OAAO,KAAK,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,YAAY,EAAE,cAAc,CAAC,EAAE,EAAE,WAAW,CAAC,CAAA;AACpF,CAAC"}
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../../../src/runtime/query/iteration/phases/plan.ts"],"names":[],"mappings":"AAEA,OAAO,EAGN,oBAAoB,EACpB,kBAAkB,GAClB,MAAM,cAAc,CAAA;AAErB,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,WAAW,CAAC,GAAqB;IACvD,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,IAAI,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;QAC1E,OAAO,UAAU,CAAA;IAClB,CAAC;IAED,MAAM,cAAc,GAAG,MAAM,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IAEpE,MAAM,GAAG,CAAC,SAAS,CAAC;QACnB,IAAI,EAAE,oBAAoB;QAC1B,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE;QACpB,YAAY,EAAE,cAAc,CAAC,EAAE;QAC/B,SAAS,EAAE,CAAC;KACZ,CAAC,CAAA;IACF,KAAK,CAAC,CAAC,GAAG,CAAC,YAAY,EAAE,CAAA;IAEzB,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,CAAC,MAAM,CAAA;IACnC,MAAM,OAAO,GAAwB;QACpC,IAAI,EAAE,eAAe;QACrB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE;QACpB,YAAY,EAAE,cAAc,CAAC,EAAE;QAC/B,IAAI,EAAE;YACL,MAAM,EAAE,IAAI,CAAC,EAAE;YACf,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC7B,EAAE,EAAE,CAAC,CAAC,EAAE;gBACR,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,QAAQ,EAAE,CAAC,CAAC,QAAQ;gBACpB,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,SAAS,EAAE,CAAC,CAAC,SAAS;gBACtB,KAAK,EAAE,CAAC,CAAC,KAAK;aACd,CAAC,CAAC;YACH,OAAO,EAAE,IAAI,CAAC,OAAO;SACrB;KACD,CAAA;IAED,wEAAwE;IACxE,sEAAsE;IACtE,gCAAgC;IAChC,EAAE;IACF,mEAAmE;IACnE,wEAAwE;IACxE,wEAAwE;IACxE,kDAAkD;IAClD,MAAM,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAA;IACrD,sEAAsE;IACtE,yEAAyE;IACzE,0EAA0E;IAC1E,yEAAyE;IACzE,sEAAsE;IACtE,uDAAuD;IACvD,MAAM,YAAY,GAAG,MAAM,oBAAoB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;IAC7D,MAAM,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,EAAE,YAAY,CAAC,CAAA;IAE/D,OAAO,KAAK,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,YAAY,EAAE,cAAc,CAAC,EAAE,EAAE,WAAW,CAAC,CAAA;AACpF,CAAC"}

package/dist/runtime/query/iteration/step-shaping.d.ts

@@ -0,0 +1,41 @@
+import { type Message, type UserMessage } from '../../../types/message/index.js';
+import type { ToolChoice } from '../../../types/provider/chat.js';
+import type { PrepareStepContext, PrepareStepResult, StepResult, StepVeto } from '../../../types/run/index.js';
+import type { Skill } from '../../../types/skills/index.js';
+import type { IterationContext } from './phases/index.js';
+/**
+ * How the next request is shaped: admission, preparation, and the context
+ * budget handed to both.
+ *
+ * Three of these read state the loop replaces or grows as it runs, so they
+ * arrive as accessors rather than as values — `latestUserMessage` is replaced
+ * on every operator turn and `steps` gains a member per step, and a captured
+ * copy of either would describe an earlier return. `ctx` is the run's own
+ * context object, passed through rather than re-derived, because
+ * `selectContextModel` WRITES two of its fields (`contextModel` and
+ * `activeProviderContextWindow`) for the compaction pass to read.
+ */
+export interface StepShaping {
+    readonly ctx: IterationContext;
+    readonly latestUserMessage: () => UserMessage | undefined;
+    readonly steps: () => readonly StepResult[];
+}
+export declare function stepContextMessage(content: string): UserMessage;
+/** Derived after request projection; never accumulates in canonical history or replaces operator intent. */
+export declare function appendWorkContext(shaping: StepShaping, messages: Message[], stepNumber: number, prepared: PrepareStepResult): void;
+export declare function stepContext(shaping: StepShaping, stepNumber: number, prepared: PrepareStepResult): PrepareStepContext;
+/** Refuse the next call on a veto or hook error; do not skip a failed admission check. */
+export declare function beforeStep(shaping: StepShaping, stepNumber: number): Promise<StepVeto | undefined>;
+/** Shape the next request. A failed tuning stage is skipped; admission belongs to beforeStep. */
+export declare function prepareStep(shaping: StepShaping, stepNumber: number): Promise<{
+    allowedTools?: string[];
+    toolChoice?: ToolChoice;
+    model?: string;
+    system?: string;
+    context?: string;
+    skills?: readonly Skill[];
+    temperature?: number;
+    maxResponseTokens?: number;
+}>;
+export declare function selectContextModel(shaping: StepShaping, model: string | undefined): Promise<void>;
+//# sourceMappingURL=step-shaping.d.ts.map

package/dist/runtime/query/iteration/step-shaping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-shaping.d.ts","sourceRoot":"","sources":["../../../../src/runtime/query/iteration/step-shaping.ts"],"names":[],"mappings":"AAKA,OAAO,EACN,KAAK,OAAO,EACZ,KAAK,WAAW,EAGhB,MAAM,iCAAiC,CAAA;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AACjE,OAAO,KAAK,EACX,kBAAkB,EAClB,iBAAiB,EACjB,UAAU,EACV,QAAQ,EACR,MAAM,6BAA6B,CAAA;AACpC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gCAAgC,CAAA;AAI3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAEzD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAA;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,WAAW,GAAG,SAAS,CAAA;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,SAAS,UAAU,EAAE,CAAA;CAC3C;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,eAKjD;AAED,4GAA4G;AAC5G,wBAAgB,iBAAiB,CAChC,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,OAAO,EAAE,EACnB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,iBAAiB,GACzB,IAAI,CAmBN;AAED,wBAAgB,WAAW,CAC1B,OAAO,EAAE,WAAW,EACpB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,iBAAiB,GACzB,kBAAkB,CAuCpB;AAED,0FAA0F;AAC1F,wBAAsB,UAAU,CAC/B,OAAO,EAAE,WAAW,EACpB,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAU/B;AAED,iGAAiG;AACjG,wBAAsB,WAAW,CAChC,OAAO,EAAE,WAAW,EACpB,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC;IACV,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,CAAA;IACzB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC1B,CAAC,CAuGD;AAED,wBAAsB,kBAAkB,CACvC,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,MAAM,GAAG,SAAS,GACvB,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/runtime/query/iteration/step-shaping.js

@@ -0,0 +1,184 @@
+import { resolveContextWindow } from '../../../compaction/context-window.js';
+import { estimateMessageTokens } from '../../../compaction/token-estimate.js';
+import { NAMZU } from '../../../constants/telemetry/index.js';
+import { renderSkillsSection } from '../../../persona/assembler.js';
+import { PreparationContextError } from '../../../run/preparation-context-error.js';
+import { createRuntimeContextMessage, createSystemMessage, } from '../../../types/message/index.js';
+import { toErrorMessage } from '../../../utils/error.js';
+import { createCallbackInference } from '../callback-inference.js';
+import { measureContext } from './phases/compaction.js';
+export function stepContextMessage(content) {
+    return createRuntimeContextMessage(`Current step context (runtime-generated; not a new user request):\n${content}`, 'step-context');
+}
+/** Derived after request projection; never accumulates in canonical history or replaces operator intent. */
+export function appendWorkContext(shaping, messages, stepNumber, prepared) {
+    const { ctx } = shaping;
+    const contributions = [
+        ctx.completionInbox?.describeOwnedWork(),
+        ctx.toolExecutor.describeFileEvidence(messages),
+    ].filter((content) => Boolean(content));
+    if (contributions.length === 0)
+        return;
+    let room = stepContext(shaping, stepNumber, prepared).contextBudget?.remainingTokens ?? 0;
+    // Leave room for the actual task; admit whole contributions, never dangling partial references.
+    if (room < 1_500)
+        return;
+    for (const content of contributions) {
+        if (!content || content.length > 8_000)
+            continue;
+        const message = stepContextMessage(content);
+        const tokens = estimateMessageTokens(message);
+        if (tokens > Math.min(2_000, room - 1_000))
+            continue;
+        messages.push(message);
+        room -= tokens;
+    }
+}
+export function stepContext(shaping, stepNumber, prepared) {
+    const { ctx, latestUserMessage, steps } = shaping;
+    const model = prepared.model ?? ctx.runConfig.model;
+    const window = resolveContextWindow(ctx.compactionConfig?.contextWindowTokens, model, model === ctx.runConfig.model
+        ? ctx.providerContextWindow
+        : model === ctx.contextModel
+            ? ctx.activeProviderContextWindow
+            : undefined);
+    const skills = prepared.skills ? renderSkillsSection([...prepared.skills]) : null;
+    const preamble = [prepared.system, skills].filter(Boolean).join('\n\n');
+    const preparedTokens = (preamble ? estimateMessageTokens(createSystemMessage(preamble)) : 0) +
+        (prepared.context ? estimateMessageTokens(stepContextMessage(prepared.context)) : 0);
+    const responseReserve = Math.min(prepared.maxResponseTokens ?? ctx.runConfig.maxResponseTokens ?? Math.floor(window.tokens / 4), Math.floor(window.tokens / 4));
+    return {
+        runId: ctx.runMgr.id,
+        stepNumber,
+        messages: ctx.runMgr.messages,
+        ...(ctx.captureRunEvidence ? { captureRunEvidence: ctx.captureRunEvidence } : {}),
+        ...(latestUserMessage() ? { latestUserMessage: latestUserMessage() } : {}),
+        signal: ctx.abortController.signal,
+        contextBudget: {
+            windowTokens: window.tokens,
+            remainingTokens: Math.max(0, Math.floor(window.tokens - measureContext(ctx).tokens - preparedTokens - responseReserve)),
+        },
+        steps: steps(),
+        prepared,
+    };
+}
+/** Refuse the next call on a veto or hook error; do not skip a failed admission check. */
+export async function beforeStep(shaping, stepNumber) {
+    const { ctx } = shaping;
+    const configured = ctx.beforeStep;
+    if (!configured)
+        return undefined;
+    try {
+        return (await configured(stepContext(shaping, stepNumber, {}))) ?? undefined;
+    }
+    catch (err) {
+        return { reason: `beforeStep threw: ${toErrorMessage(err)}` };
+    }
+}
+/** Shape the next request. A failed tuning stage is skipped; admission belongs to beforeStep. */
+export async function prepareStep(shaping, stepNumber) {
+    const { ctx } = shaping;
+    const configured = ctx.prepareStep;
+    if (!configured)
+        return {};
+    const stages = Array.isArray(configured) ? configured : [configured];
+    // Folded in DECLARATION order, each stage seeing what the ones
+    // before it decided. A later stage overriding a field is last-writer
+    // wins — visibly, because the order is a line in the host's code
+    // rather than an accident of install history.
+    let result = {};
+    for (const stage of stages) {
+        const inference = createCallbackInference(ctx, result.model ?? ctx.runConfig.model, 'preparation');
+        try {
+            const decided = await stage({
+                ...stepContext(shaping, stepNumber, result),
+                generateText: inference.generateText,
+            });
+            if (decided)
+                result = { ...result, ...decided };
+            await selectContextModel(shaping, result.model ?? ctx.runConfig.model);
+        }
+        catch (err) {
+            // Skipped, and the rest still run: one broken concern must
+            // not silently disable the others it was declared beside.
+            ctx.log.error('a prepareStep stage threw — skipping it', {
+                [NAMZU.RUN_ID]: ctx.runMgr.id,
+                'namzu.runtime.step_number': stepNumber,
+                'exception.message': toErrorMessage(err),
+            });
+            // An SDK stage may report availability and validated fallback evidence
+            // without exposing its error. Preserve prior decisions and the context budget;
+            // ordinary exceptions still contribute nothing to the model request.
+            if (err instanceof PreparationContextError && !ctx.abortController.signal.aborted) {
+                const room = stepContext(shaping, stepNumber, result).contextBudget?.remainingTokens ?? 0;
+                if (typeof err.context === 'string' &&
+                    err.context.length > 0 &&
+                    err.context.length + (result.context ? 2 : 0) <= Math.min(12_000, Math.floor(room)))
+                    result = {
+                        ...result,
+                        context: [result.context, err.context].filter(Boolean).join('\n\n'),
+                    };
+            }
+        }
+        finally {
+            inference.close();
+        }
+    }
+    const prepared = {};
+    if (result.activeTools) {
+        const known = result.activeTools.filter((name) => ctx.tools.has(name));
+        const unknown = result.activeTools.filter((name) => !ctx.tools.has(name));
+        if (unknown.length > 0) {
+            // The all-unknown case gets its own sentence because it has its
+            // own consequence. Some names dropped narrows the step; ALL of
+            // them dropped leaves it able to call nothing — which is the
+            // honest reading of "only these tools" when none of them exist,
+            // and is not what a reader of "ignoring them" would expect.
+            //
+            // Widening back to the run's list would be worse: it grants
+            // exactly the tools the caller asked to exclude, on the grounds
+            // that their own list failed. A step that can call nothing is
+            // constrained; a step that can call everything is a control
+            // that stopped applying.
+            const message = known.length === 0
+                ? 'prepareStep named only tools that are not registered — this step can call nothing'
+                : 'prepareStep named tools that are not registered — ignoring them';
+            ctx.log.warn(message, {
+                [NAMZU.RUN_ID]: ctx.runMgr.id,
+                'namzu.runtime.step_number': stepNumber,
+                'namzu.runtime.unknown': unknown,
+                'namzu.runtime.remaining': known.length,
+            });
+        }
+        prepared.allowedTools = known;
+    }
+    if (result.toolChoice !== undefined)
+        prepared.toolChoice = result.toolChoice;
+    if (result.model !== undefined)
+        prepared.model = result.model;
+    if (result.system !== undefined)
+        prepared.system = result.system;
+    if (result.context !== undefined)
+        prepared.context = result.context;
+    if (result.skills !== undefined)
+        prepared.skills = result.skills;
+    if (result.temperature !== undefined)
+        prepared.temperature = result.temperature;
+    if (result.maxResponseTokens !== undefined) {
+        prepared.maxResponseTokens = result.maxResponseTokens;
+    }
+    return prepared;
+}
+export async function selectContextModel(shaping, model) {
+    const { ctx } = shaping;
+    if (model !== (ctx.contextModel ?? ctx.runConfig.model)) {
+        // A measurement from another tokenizer cannot price the new request.
+        ctx.runMgr.clearLastPromptTokens();
+    }
+    ctx.contextModel = model;
+    ctx.activeProviderContextWindow =
+        model && model !== ctx.runConfig.model && !ctx.compactionConfig?.contextWindowTokens
+            ? await ctx.resolveModelContextWindow?.(model)
+            : undefined;
+}
+//# sourceMappingURL=step-shaping.js.map