@apo-ai/sdk 0.10.1 → 0.12.0

package/dist/agent-task/public.js

@@ -9,28 +9,240 @@ import {
   resolveApoAuthHeaders,
   withApoRun,
   withApoRunSync
-} from "../chunk-LO343UZO.js";
+} from "../chunk-P24ECOI3.js";
 import {
   createApoTracer
 } from "../chunk-OZWOLCJ5.js";
 import "../chunk-HRYXLRXJ.js";
 import {
   createApoOpenAI
-} from "../chunk-P43KL5AR.js";
+} from "../chunk-A3UYQ7M4.js";
 import {
   createApoAnthropic
-} from "../chunk-6H2GACBG.js";
+} from "../chunk-X73JGMK3.js";
 import {
   servingHostFromBaseURL
-} from "../chunk-Z64A566W.js";
+} from "../chunk-JTWQD27M.js";
+
+// src/agent-task/run/steer-scheduler.ts
+var TASK_STEER_SPAN_NAME = "task.steer";
+function createSteerScheduler(options) {
+  const { specs, session, trace: trace2 } = options;
+  const states = specs.map((spec, index) => ({
+    spec,
+    fired: false,
+    record: {
+      number: index + 1,
+      turn: spec.turn ?? 1,
+      ...spec.label !== void 0 ? { label: spec.label } : {},
+      trigger: spec.when,
+      message: spec.message,
+      status: "undelivered"
+    }
+  }));
+  const toolResults = /* @__PURE__ */ new Map();
+  const assistantReplies = /* @__PURE__ */ new Map();
+  const activeTurns = /* @__PURE__ */ new Set();
+  const runStartSeen = /* @__PURE__ */ new Set();
+  const progressSeen = /* @__PURE__ */ new Set();
+  let chain = Promise.resolve();
+  const enqueue = (step) => {
+    const next = chain.then(step, step);
+    chain = next.catch(() => {
+    });
+    return next;
+  };
+  function emitSteerEvent(record) {
+    try {
+      trace2.recordEvent({
+        step_name: TASK_STEER_SPAN_NAME,
+        observation_type: "CHAIN",
+        parent_call_id: options.turnSpanId?.(record.turn),
+        metadata: {
+          steerNumber: record.number,
+          turn: record.turn,
+          ...record.label !== void 0 ? { label: record.label } : {},
+          trigger: JSON.stringify(record.trigger),
+          status: record.status,
+          ...record.boundary !== void 0 ? { boundary: record.boundary } : {},
+          ...record.reason !== void 0 ? { reason: record.reason } : {}
+        },
+        output: { ...record }
+      });
+    } catch {
+    }
+  }
+  function notifyHost(record) {
+    try {
+      options.onSteer?.(record);
+    } catch (error) {
+      console.error(
+        "[AgentTask] onSteer callback failed:",
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  function finalize(state, reason) {
+    state.record.status = "undelivered";
+    state.record.reason = reason;
+    emitSteerEvent(state.record);
+    notifyHost(state.record);
+  }
+  async function deliver(state, turnNumber) {
+    state.fired = true;
+    try {
+      const result = await session.steer?.(state.spec.message, {
+        trace: trace2,
+        turnNumber,
+        steerNumber: state.record.number
+      });
+      state.record.status = "delivered";
+      state.record.deliveredAt = (/* @__PURE__ */ new Date()).toISOString();
+      state.record.boundary = result?.boundary ?? "tool_results";
+    } catch (error) {
+      state.record.status = "error";
+      state.record.reason = error instanceof Error ? error.message : String(error);
+    }
+    emitSteerEvent(state.record);
+    notifyHost(state.record);
+  }
+  function triggerSatisfied(trigger, turnNumber) {
+    if (trigger === "runStart") return runStartSeen.has(turnNumber);
+    if ("toolResults" in trigger) {
+      return (toolResults.get(turnNumber) ?? 0) >= trigger.toolResults;
+    }
+    return (assistantReplies.get(turnNumber) ?? 0) >= trigger.assistantReply;
+  }
+  return {
+    onTurnStart(turnNumber) {
+      return enqueue(async () => {
+        toolResults.set(turnNumber, 0);
+        assistantReplies.set(turnNumber, 0);
+        activeTurns.add(turnNumber);
+      });
+    },
+    onProgressEvent(turnNumber, event) {
+      return enqueue(async () => {
+        if (!activeTurns.has(turnNumber)) return;
+        progressSeen.add(turnNumber);
+        if (event.kind === "run_start") {
+          runStartSeen.add(turnNumber);
+        } else if (event.kind === "tool_result") {
+          toolResults.set(turnNumber, (toolResults.get(turnNumber) ?? 0) + 1);
+        } else if (event.kind === "assistant_reply") {
+          assistantReplies.set(turnNumber, (assistantReplies.get(turnNumber) ?? 0) + 1);
+        }
+        for (const state of states) {
+          if (state.fired || state.record.turn !== turnNumber) continue;
+          if (triggerSatisfied(state.spec.when, turnNumber)) {
+            await deliver(state, turnNumber);
+          }
+        }
+      });
+    },
+    onTurnEnd(turnNumber) {
+      return enqueue(async () => {
+        activeTurns.delete(turnNumber);
+        const reason = progressSeen.has(turnNumber) ? "turn ended before trigger fired" : "no progress events observed for this turn (adapter did not call notifyAgentEvent)";
+        for (const state of states) {
+          if (state.fired || state.record.turn !== turnNumber) continue;
+          finalize(state, reason);
+        }
+      });
+    },
+    onRunEnd(maxTurnReached) {
+      return enqueue(async () => {
+        for (const state of states) {
+          if (state.fired || state.record.status !== "undelivered") continue;
+          if (state.record.turn > maxTurnReached) {
+            finalize(state, "target turn never ran");
+          }
+        }
+      });
+    },
+    recordsByTurn() {
+      const byTurn = /* @__PURE__ */ new Map();
+      for (const state of states) {
+        const list = byTurn.get(state.record.turn) ?? [];
+        list.push(state.record);
+        byTurn.set(state.record.turn, list);
+      }
+      return byTurn;
+    }
+  };
+}
 
 // src/agent-task/trace-projection/view.ts
 var TASK_TURN_SPAN_NAME = "task.turn";
+function steerRecordFrom(obs) {
+  const output = obs.output;
+  if (!output || typeof output !== "object") return void 0;
+  const asRecord2 = (v) => v !== null && typeof v === "object" && typeof v.number === "number" ? v : void 0;
+  const direct = asRecord2(output);
+  if (direct) return direct;
+  const tryParse = (text) => {
+    if (typeof text !== "string") return void 0;
+    try {
+      return asRecord2(JSON.parse(text));
+    } catch {
+      return void 0;
+    }
+  };
+  const fromText = tryParse(output.text);
+  if (fromText) return fromText;
+  const messages = output.messages;
+  if (Array.isArray(messages)) {
+    const content = messages[0]?.content;
+    const fromMessage = tryParse(content);
+    if (fromMessage) return fromMessage;
+  }
+  return void 0;
+}
+function traceSteerFrom(obs) {
+  const meta = obs.metadata;
+  const record = steerRecordFrom(obs);
+  const number = typeof record?.number === "number" ? record.number : typeof meta?.steerNumber === "number" ? meta.steerNumber : void 0;
+  if (number === void 0) return void 0;
+  const source = record ?? {};
+  const read = (key) => source[key] !== void 0 ? source[key] : meta?.[key];
+  const status = read("status");
+  const steer2 = {
+    number,
+    spanId: obs.spanId,
+    turn: typeof read("turn") === "number" ? read("turn") : 1,
+    trigger: triggerToString(read("trigger")),
+    message: source.message,
+    ...isSteerStatus(status) ? { status } : { status: "undelivered" }
+  };
+  const label = read("label");
+  if (typeof label === "string") steer2.label = label;
+  const deliveredAt = read("deliveredAt");
+  if (typeof deliveredAt === "string") steer2.deliveredAt = deliveredAt;
+  if (obs.startedAt !== void 0) steer2.spanStartedAt = obs.startedAt;
+  const boundary = read("boundary");
+  if (typeof boundary === "string") steer2.boundary = boundary;
+  const reason = read("reason");
+  if (typeof reason === "string") steer2.reason = reason;
+  return steer2;
+}
+function isSteerStatus(v) {
+  return v === "delivered" || v === "undelivered" || v === "error";
+}
+function triggerToString(v) {
+  if (typeof v === "string") return v;
+  if (v !== null && typeof v === "object") {
+    try {
+      return JSON.stringify(v) ?? "unknown";
+    } catch {
+    }
+  }
+  return "unknown";
+}
 function invocationOrderKey(obs) {
   const hasTs = obs.startedAt != null ? 0 : 1;
   return [hasTs, obs.startedAt ?? "", obs.spanId];
 }
-var TraceView = class {
+var TraceView = class _TraceView {
   constructor(snapshot) {
     this.snapshot = snapshot;
   }
@@ -79,6 +291,56 @@ var TraceView = class {
       startedAt: o.startedAt
     }));
   }
+  /**
+   * Mid-run steers, derived from `task.steer` observations, in number order.
+   * Empty when the trace carries none — steering assertions fail closed on
+   * the empty case instead of passing vacuously.
+   */
+  get steers() {
+    const out = [];
+    for (const obs of this.sortedObservations) {
+      if (obs.name !== TASK_STEER_SPAN_NAME) continue;
+      const steer2 = traceSteerFrom(obs);
+      if (steer2) out.push(steer2);
+    }
+    return out.sort((a, b) => a.number - b.number);
+  }
+  /**
+   * Whether an observation started after the steer observation, using the
+   * same ordering key as everywhere else in this class (startedAt, then
+   * span id). The id tie-break matters on the local tee path, whose ISO
+   * timestamps truncate to milliseconds — a steer and the generation that
+   * consumes it can share one.
+   */
+  static startedAfter(obs, steer2) {
+    if (obs.startedAt == null) return true;
+    if (steer2.spanStartedAt == null) return false;
+    if (obs.startedAt !== steer2.spanStartedAt) {
+      return obs.startedAt > steer2.spanStartedAt;
+    }
+    return obs.spanId > steer2.spanId;
+  }
+  /**
+   * A TraceView over the run after steer n was delivered: observations that
+   * started after the steer's delivery timestamp (the first generation that
+   * consumed it through run end). Missing timestamps sort after timestamped
+   * observations per the projection contract, so they belong to the window
+   * too. An undelivered steer yields an empty view — assertions inside it
+   * fail on missing evidence rather than passing vacuously.
+   */
+  windowAfterSteer(n) {
+    const steer2 = this.steers.find((s) => s.number === n);
+    if (!steer2) {
+      throw new Error(`No steer number ${n} in this trace.`);
+    }
+    if (steer2.spanStartedAt === void 0) {
+      return new _TraceView({ ...this.snapshot, observations: [] });
+    }
+    const filtered = this.snapshot.observations.filter(
+      (o) => o.spanId !== steer2.spanId && _TraceView.startedAfter(o, steer2)
+    );
+    return new _TraceView({ ...this.snapshot, observations: filtered });
+  }
   /** Last assistant message content — the agent's "reply". Empty if none. */
   get reply() {
     const msgs = this.messages;
@@ -382,7 +644,186 @@ function levenshtein(a, b) {
 // src/agent-task/checks/judge.ts
 import { createHash } from "crypto";
 
+// src/agent-task/checks/reasoning-loop.ts
+var MAX_UNIT_CHARS = 64;
+var MIN_UNIT_COPIES = 100;
+var MIN_REPEAT_CHARS = 1e3;
+var MAX_CHAR_RUN = 3;
+var GRAM = 24;
+var DIVERSITY_WINDOW = 3e3;
+var MIN_DIVERSITY = 0.1;
+var DIVERSITY_STRIDE = 256;
+var MAX_DIVERSITY_LINE_CHARS = 2e3;
+var RECYCLE_GRAM = 32;
+var RECYCLE_WINDOW = 5e3;
+var MAX_RECYCLED = 0.95;
+var isFoldable = (ch) => /[\p{L}\p{N}]/u.test(ch);
+function foldForRepetition(text) {
+  let out = "";
+  let last = "";
+  let run = 0;
+  for (const raw of text) {
+    if (!isFoldable(raw)) continue;
+    const ch = raw.toLowerCase();
+    run = ch === last ? run + 1 : 1;
+    last = ch;
+    if (run <= MAX_CHAR_RUN) out += ch;
+  }
+  return out;
+}
+function isTableLine(line) {
+  const trimmed = line.trim();
+  if (trimmed.startsWith("|")) return true;
+  return (trimmed.match(/\|/g)?.length ?? 0) >= 3;
+}
+function diversity(folded) {
+  const total = folded.length - GRAM + 1;
+  if (total <= 0) return 1;
+  const grams = /* @__PURE__ */ new Set();
+  for (let i = 0; i < total; i++) grams.add(folded.slice(i, i + GRAM));
+  return grams.size / total;
+}
+var RepetitionGuard = class {
+  constructor(opts) {
+    this.rawChars = 0;
+    // Repeated-unit state: the folded tail, and for each period p the number
+    // of consecutive folded chars equal to the char p before them.
+    this.tail = "";
+    this.lastChar = "";
+    this.charRun = 0;
+    this.periodRuns = new Array(MAX_UNIT_CHARS + 1).fill(0);
+    // Low-diversity state: the current raw line, and the folded window built
+    // from finished lines that are not tables.
+    this.line = "";
+    this.window = "";
+    this.sinceMeasured = 0;
+    // Recycled state: every gram of the filtered folded stream so far, and for
+    // the window's grams whether each had been seen when it arrived.
+    this.seenGrams = /* @__PURE__ */ new Set();
+    this.gramTail = "";
+    this.windowFlags = [];
+    this.flagHead = 0;
+    this.recycledInWindow = 0;
+    this.checkDiversity = opts.diversity;
+  }
+  get tripped() {
+    return this.trip;
+  }
+  push(delta) {
+    if (this.trip || !delta) return this.trip;
+    for (const raw of delta) {
+      this.rawChars++;
+      if (this.checkDiversity) this.pushLineChar(raw);
+      if (isFoldable(raw)) this.pushFolded(raw.toLowerCase());
+      if (this.trip) break;
+    }
+    return this.trip;
+  }
+  pushFolded(ch) {
+    this.charRun = ch === this.lastChar ? this.charRun + 1 : 1;
+    this.lastChar = ch;
+    if (this.charRun > MAX_CHAR_RUN) return;
+    this.tail += ch;
+    const n = this.tail.length - 1;
+    for (let p = 1; p <= MAX_UNIT_CHARS; p++) {
+      this.periodRuns[p] = n >= p && this.tail[n - p] === ch ? this.periodRuns[p] + 1 : 0;
+      const span = this.periodRuns[p] + p;
+      if (span >= MIN_REPEAT_CHARS && span / p >= MIN_UNIT_COPIES) {
+        this.trip = {
+          rule: "repeated-unit",
+          atChar: this.rawChars,
+          unit: this.tail.slice(-p),
+          copies: Math.floor(span / p)
+        };
+        return;
+      }
+    }
+    if (this.tail.length > MAX_UNIT_CHARS * 2) this.tail = this.tail.slice(-MAX_UNIT_CHARS);
+  }
+  pushLineChar(raw) {
+    if (raw !== "\n") {
+      if (this.line.length <= MAX_DIVERSITY_LINE_CHARS) this.line += raw;
+      return;
+    }
+    const line = this.line;
+    this.line = "";
+    if (line.length > MAX_DIVERSITY_LINE_CHARS || isTableLine(line)) return;
+    const folded = foldForRepetition(line);
+    if (!folded) return;
+    this.pushRecycled(folded);
+    this.window = (this.window + folded).slice(-DIVERSITY_WINDOW);
+    this.sinceMeasured += folded.length;
+    if (this.window.length < DIVERSITY_WINDOW || this.sinceMeasured < DIVERSITY_STRIDE) return;
+    this.sinceMeasured = 0;
+    const ratio = diversity(this.window);
+    if (ratio < MIN_DIVERSITY) {
+      this.trip = { rule: "low-diversity", atChar: this.rawChars, diversity: ratio };
+      return;
+    }
+    const windowGrams = this.windowFlags.length - this.flagHead;
+    if (windowGrams < RECYCLE_WINDOW) return;
+    const recycled = this.recycledInWindow / windowGrams;
+    if (recycled >= MAX_RECYCLED) {
+      this.trip = { rule: "recycled", atChar: this.rawChars, recycled };
+    }
+  }
+  pushRecycled(folded) {
+    for (const ch of folded) {
+      this.gramTail = (this.gramTail + ch).slice(-RECYCLE_GRAM);
+      if (this.gramTail.length < RECYCLE_GRAM) continue;
+      const seen = this.seenGrams.has(this.gramTail);
+      if (!seen) this.seenGrams.add(this.gramTail);
+      this.windowFlags.push(seen);
+      if (seen) this.recycledInWindow++;
+      if (this.windowFlags.length - this.flagHead > RECYCLE_WINDOW) {
+        if (this.windowFlags[this.flagHead++]) this.recycledInWindow--;
+      }
+    }
+    if (this.flagHead > RECYCLE_WINDOW * 4) {
+      this.windowFlags.splice(0, this.flagHead);
+      this.flagHead = 0;
+    }
+  }
+};
+function describeTrip(trip) {
+  switch (trip.rule) {
+    case "repeated-unit":
+      return `"${trip.unit}" repeated ${trip.copies}\xD7 at char ${trip.atChar}`;
+    case "low-diversity":
+      return `distinct-${GRAM}-gram ratio ${trip.diversity.toFixed(3)} at char ${trip.atChar}`;
+    case "recycled":
+      return `${Math.round(trip.recycled * 100)}% of the last ${RECYCLE_WINDOW} chars replay earlier reasoning, at char ${trip.atChar}`;
+  }
+}
+
 // src/agent-task/checks/second-judge.ts
+function secondJudgeFacts(check) {
+  const sj = check.judge?.secondJudge;
+  if (!sj) return { kind: "none" };
+  if (sj.skipped) return { kind: "skipped" };
+  if (sj.error || sj.choice == null) return { kind: "error" };
+  const conf = sj.confidence ?? 0;
+  if (sj.choice === "pass" !== (check.pass === true)) {
+    return { kind: "split", confidence: conf };
+  }
+  if (conf < 0.6) return { kind: "unsure", confidence: conf };
+  return { kind: "agree", confidence: conf };
+}
+function secondJudgeTakeaway(check) {
+  const facts = secondJudgeFacts(check);
+  switch (facts.kind) {
+    case "split":
+      return `Verdicts differ \u2014 second judge contradicts at ${facts.confidence.toFixed(2)} confidence.`;
+    case "unsure":
+      return `Second judge unsure (${facts.confidence.toFixed(2)}) \u2014 weak corroboration.`;
+    case "error":
+      return `Second opinion failed to arrive${check.judge?.secondJudge?.error ? ` (${check.judge.secondJudge.error})` : ""}.`;
+    case "skipped":
+      return `Second opinion skipped${check.judge?.secondJudge?.skipped ? ` \u2014 ${check.judge.secondJudge.skipped}` : ""}.`;
+    default:
+      return null;
+  }
+}
 var SECOND_JUDGE_TIMEOUT_MS = 3e4;
 var OPENROUTER_RESERVED_HINT = "Point APO_SECOND_JUDGE_BASE_URL at an OpenRouter-style decisions API (e.g. https://openrouter.ai/api/v1) or set APO_SECOND_JUDGE_PROVIDER=openrouter";
 var openRouterProvider = {
@@ -461,9 +902,24 @@ function resolveSecondJudgeProvider(baseURL) {
   }
   return /(^|\.)api\.openai\.com$/.test(new URL(baseURL).hostname) ? openAIProvider : openRouterProvider;
 }
+var INPUT_TOO_LARGE_MARKERS = [
+  "max_tokens_exceeded",
+  "context_length_exceeded",
+  "maximum context length"
+];
+function isInputTooLargeRejection(status, body) {
+  if (status !== 400 && status !== 413) return false;
+  return INPUT_TOO_LARGE_MARKERS.some((marker2) => body.includes(marker2));
+}
+function estimateTokens(text) {
+  return Math.round(text.length / 4 / 1e3) * 1e3;
+}
 async function callSecondJudge(args) {
   const startedAt = Date.now();
-  const evidence = { model: args.model };
+  const evidence = {
+    model: args.model,
+    ...args.projected ? { projected: true } : {}
+  };
   try {
     const provider = resolveSecondJudgeProvider(args.baseURL);
     if (provider.reserved) {
@@ -481,6 +937,10 @@ async function callSecondJudge(args) {
     });
     if (!response.ok) {
       const body = await response.text().catch(() => "");
+      if (isInputTooLargeRejection(response.status, body)) {
+        evidence.skipped = `input ~${estimateTokens(args.state).toLocaleString("en-US")} tokens exceeds ${args.model}'s context limit \u2014 project a smaller view with t.judge(value, instruction, { secondJudgeValue })`;
+        return evidence;
+      }
       evidence.error = `Second judge API ${response.status}: ${body.slice(0, 200)}`;
       return evidence;
     }
@@ -520,8 +980,19 @@ var JudgeUnavailableError = class extends Error {
     this.name = "JudgeUnavailableError";
   }
 };
-var VERDICT_FIRST_CONTRACT = 'Respond with ONLY a JSON object: {"pass": true/false, "reasoning": "your reasoning"}';
-var REASONING_FIRST_CONTRACT = 'Respond with ONLY a JSON object: {"reasoning": "your reasoning", "pass": true/false}';
+var JudgeReasoningLoopError = class extends JudgeUnavailableError {
+  constructor(trip, channel) {
+    super(`judge reasoning loop: ${channel} ${describeTrip(trip)}`);
+    this.name = "JudgeReasoningLoopError";
+  }
+};
+function isJudgeLoopGuardEnabled() {
+  const value = process.env.APO_JUDGE_LOOP_GUARD?.trim().toLowerCase();
+  return value !== "0" && value !== "false" && value !== "off";
+}
+var QUOTE_RULE = " Inside the reasoning, quote the output with single quotes, never with unescaped double quotes.";
+var VERDICT_FIRST_CONTRACT = 'Respond with ONLY a JSON object: {"pass": true/false, "reasoning": "your reasoning"}.' + QUOTE_RULE;
+var REASONING_FIRST_CONTRACT = 'Respond with ONLY a JSON object: {"reasoning": "your reasoning", "pass": true/false}.' + QUOTE_RULE;
 function isJudgeVerdictFirstOverrideEnabled() {
   const value = process.env.APO_JUDGE_VERDICT_FIRST?.trim().toLowerCase();
   return value === "1" || value === "true";
@@ -532,6 +1003,23 @@ function judgeResponseContract() {
 function judgeContractInUse() {
   return isJudgeVerdictFirstOverrideEnabled() ? "verdict-first" : "reasoning-first";
 }
+function judgeResponseFormat() {
+  const properties = isJudgeVerdictFirstOverrideEnabled() ? { pass: { type: "boolean" }, reasoning: { type: "string" } } : { reasoning: { type: "string" }, pass: { type: "boolean" } };
+  return {
+    type: "json_schema",
+    json_schema: {
+      name: "judge_verdict",
+      strict: true,
+      schema: {
+        type: "object",
+        properties,
+        required: Object.keys(properties),
+        additionalProperties: false
+      }
+    }
+  };
+}
+var JSON_OBJECT_FORMAT = { type: "json_object" };
 function judgeSystemPrompt() {
   return `You are an evaluation judge. Evaluate the given value(s) against the instruction. ${judgeResponseContract()}`;
 }
@@ -590,9 +1078,14 @@ function parseJudgeJson(raw) {
     } catch {
     }
   }
+  return {};
+}
+function judgeVerdict(raw) {
+  const parsed = parseJudgeJson(raw);
+  if (typeof parsed.pass !== "boolean") return void 0;
   return {
-    pass: false,
-    reasoning: "Judge response could not be parsed as JSON \u2014 the verdict is unknown, so this check is treated as a failure. The model's raw response is available in the judge metadata."
+    pass: parsed.pass,
+    reasoning: typeof parsed.reasoning === "string" ? parsed.reasoning : ""
   };
 }
 var JUDGE_IDLE_TIMEOUT_MS = 9e4;
@@ -621,7 +1114,7 @@ function retryDelayMs(retryAfter) {
   if (!Number.isFinite(ms)) return JUDGE_RETRY_DELAY_MS;
   return Math.min(Math.max(ms, JUDGE_RETRY_DELAY_MS), JUDGE_RETRY_AFTER_CAP_MS);
 }
-async function readCompletion(response, onData) {
+async function readCompletion(response, onData, guards) {
   const contentType = response.headers.get("content-type") ?? "";
   if (!contentType.includes("text/event-stream")) {
     const data = await response.json();
@@ -658,7 +1151,15 @@ async function readCompletion(response, onData) {
     }
     if (!chunk) return;
     const choice = chunk.choices?.[0];
-    text += choice?.delta?.content ?? "";
+    const content = choice?.delta?.content ?? "";
+    text += content;
+    if (guards) {
+      const thinking = choice?.delta?.reasoning_content ?? choice?.delta?.reasoning ?? "";
+      const reasoningTrip = guards.reasoning.push(thinking);
+      if (reasoningTrip) throw new JudgeReasoningLoopError(reasoningTrip, "reasoning");
+      const contentTrip = guards.content.push(content);
+      if (contentTrip) throw new JudgeReasoningLoopError(contentTrip, "content");
+    }
     if (choice?.finish_reason) finishReason = choice.finish_reason;
     if (chunk.usage) usage = chunk.usage;
   };
@@ -735,33 +1236,32 @@ function runWithSharedPrefix(key, task2) {
   );
   return next;
 }
+function defaultJudgeBaseURL(baseURL) {
+  return baseURL ?? process.env.OPENROUTER_BASE_URL ?? "https://openrouter.ai/api/v1";
+}
+function defaultJudgeAPIKey(apiKey) {
+  return apiKey ?? process.env.OPENROUTER_API_KEY ?? process.env.OPENAI_API_KEY;
+}
 async function callJudge(args) {
-  const baseURL = args.baseURL ?? process.env.OPENROUTER_BASE_URL ?? "https://openrouter.ai/api/v1";
-  const apiKey = args.apiKey ?? process.env.OPENROUTER_API_KEY ?? process.env.OPENAI_API_KEY;
-  const deliverableText = `Values to evaluate:
-${formatJudgeValues(args.values)}`;
-  const { briefingText, instructionText } = assembleBriefing(args);
-  const systemPromptText = `${briefingText}
-
-${deliverableText}`;
+  const baseURL = defaultJudgeBaseURL(args.baseURL);
+  const apiKey = defaultJudgeAPIKey(args.apiKey);
+  const { briefingText, instructionText, systemPromptText, deliverableText, secondJudgeState, secondJudgeProjected } = buildJudgePromptParts({
+    values: args.values,
+    instruction: args.instruction,
+    ...args.prompt ? { prompt: args.prompt } : {},
+    ...args.context ? { context: args.context } : {},
+    ...args.secondJudgeValue !== void 0 ? { secondJudgeValue: args.secondJudgeValue } : {}
+  });
   const secondJudgeModel = resolveSecondJudgeModel();
-  const secondJudgeProjected = args.secondJudgeValue !== void 0;
-  const secondJudgeValues = args.secondJudgeValue ?? args.values;
-  const secondJudgeDeliverableText = `Values to evaluate:
-${formatJudgeValues(secondJudgeValues)}`;
-  const secondJudgePromise = secondJudgeModel ? callSecondJudge({
-    state: `${briefingText}
-
-${secondJudgeDeliverableText}
-
-${instructionText}`,
+  const secondJudgePromise = args.prefetchedSecondJudge ? Promise.resolve(args.prefetchedSecondJudge) : secondJudgeModel ? callSecondJudge({
+    state: secondJudgeState,
     model: secondJudgeModel,
     baseURL: resolveSecondJudgeBaseURL(baseURL),
     apiKey: resolveSecondJudgeAPIKey(apiKey),
     ...secondJudgeProjected ? { projected: true } : {}
   }) : void 0;
   const cacheKey = `${args.model}\0${briefingText}\0${deliverableText}`;
-  const requestBody = (stream) => JSON.stringify({
+  const requestBody = (stream, schema) => JSON.stringify({
     model: args.model,
     prompt_cache_key: promptCacheKey(cacheKey),
     messages: [
@@ -779,10 +1279,10 @@ ${instructionText}`,
       { role: "user", content: instructionText }
     ],
     temperature: 0,
-    response_format: { type: "json_object" },
+    response_format: schema ? judgeResponseFormat() : JSON_OBJECT_FORMAT,
     ...stream ? { stream: true, stream_options: { include_usage: true } } : {}
   });
-  const attempt = async (stream, maxDeadline) => {
+  const attempt = async (stream, schema, maxDeadline) => {
     const controller = new AbortController();
     const expire = (reason, name) => () => controller.abort(new DOMException(reason, name));
     const firstDataMs = judgeFirstDataTimeoutMs();
@@ -818,7 +1318,7 @@ ${instructionText}`,
             "Content-Type": "application/json",
             ...apiKey ? { Authorization: `Bearer ${apiKey}` } : {}
           },
-          body: requestBody(stream)
+          body: requestBody(stream, schema)
         });
       } catch (error) {
         return transportFailure("Judge request failed", controller.signal.reason ?? error);
@@ -832,12 +1332,20 @@ ${instructionText}`,
           ...isRetryableStatus(response.status) ? { retryDelayMs: retryDelayMs(response.headers.get("retry-after")) } : {},
           // Name the field, not the word: gateways echo request params in
           // unrelated 400 bodies.
-          ...stream && response.status === 400 && /stream_options|["'`]stream["'`]/.test(body) ? { streamRejected: true } : {}
+          ...stream && response.status === 400 && /stream_options|["'`]stream["'`]/.test(body) ? { streamRejected: true } : {},
+          ...schema && response.status === 400 && /json_schema|response_format/.test(body) ? { schemaRejected: true } : {}
         };
       }
+      const guards = isJudgeLoopGuardEnabled() ? {
+        reasoning: new RepetitionGuard({ diversity: true }),
+        content: new RepetitionGuard({ diversity: false })
+      } : void 0;
       try {
-        return { kind: "completion", completion: await readCompletion(response, onData) };
+        return { kind: "completion", completion: await readCompletion(response, onData, guards) };
       } catch (error) {
+        if (error instanceof JudgeReasoningLoopError) {
+          return { kind: "unavailable", error, retryable: true, loop: true };
+        }
         return transportFailure("Judge response failed", controller.signal.reason ?? error);
       }
     } finally {
@@ -864,17 +1372,23 @@ ${instructionText}`,
     const startedAt = Date.now();
     const deadline = startedAt + judgeMaxDurationMs();
     let stream = true;
-    let result = await attempt(stream, deadline);
-    const truncated = result.kind === "completion" && isTruncated(result.completion);
-    const streamRejected = result.kind === "unavailable" && result.streamRejected === true;
+    let schema = true;
+    let result = await attempt(stream, schema, deadline);
+    while (result.kind === "unavailable" && (result.streamRejected || result.schemaRejected)) {
+      if (result.streamRejected) stream = false;
+      if (result.schemaRejected) schema = false;
+      result = await attempt(stream, schema, deadline);
+    }
+    let loops = result.kind === "unavailable" && result.loop ? 1 : 0;
+    const noVerdict = (r) => r.kind === "completion" && (isTruncated(r.completion) || judgeVerdict(r.completion.text) === void 0);
     const retryable = result.kind === "unavailable" && result.retryable;
-    if (truncated || streamRejected || retryable) {
-      const delay = result.kind === "unavailable" && result.retryDelayMs !== void 0 ? result.retryDelayMs : streamRejected ? 0 : JUDGE_RETRY_DELAY_MS;
+    if (noVerdict(result) || retryable) {
+      const delay = result.kind === "unavailable" && result.retryDelayMs !== void 0 ? result.retryDelayMs : JUDGE_RETRY_DELAY_MS;
       if (deadline - Date.now() - delay >= JUDGE_MIN_RETRY_BUDGET_MS) {
-        if (streamRejected) stream = false;
         await new Promise((resolve5) => setTimeout(resolve5, delay));
         const first = result;
-        result = await attempt(stream, deadline);
+        result = await attempt(stream, schema, deadline);
+        if (result.kind === "unavailable" && result.loop) loops++;
         if (result.kind === "unavailable" && first.kind === "unavailable") {
           result = {
             ...result,
@@ -885,17 +1399,25 @@ ${instructionText}`,
         }
       }
     }
-    if (result.kind === "unavailable") throw result.error;
-    const { text, usage } = result.completion;
-    const judge = {
+    const judgeMetadata = async (completion) => ({
       model: args.model,
       contract: judgeContractInUse(),
       prompt: { system: systemPromptText, user: instructionText },
-      response: text,
-      tokens: parseJudgeUsage(usage),
+      ...completion ? { response: completion.text, tokens: parseJudgeUsage(completion.usage) } : {},
       latency_ms: Date.now() - startedAt,
-      secondJudge: await secondJudgePromise
-    };
+      secondJudge: await secondJudgePromise,
+      ...loops > 0 ? { reasoning_loops: loops } : {}
+    });
+    if (result.kind === "unavailable" && result.loop) {
+      return {
+        pass: false,
+        reasoning: `Judge reasoning loop \u2014 the judge's stream degenerated into repetition and was cut${loops > 1 ? ", on the retry too" : ""} (${result.error.message}). The verdict is unknown, so this check is recorded as a judge error, not a verdict.`,
+        judge: await judgeMetadata(),
+        unavailable: true
+      };
+    }
+    if (result.kind === "unavailable") throw result.error;
+    const judge = await judgeMetadata(result.completion);
     if (isTruncated(result.completion)) {
       return {
         pass: false,
@@ -904,12 +1426,16 @@ ${instructionText}`,
         unavailable: true
       };
     }
-    const parsed = parseJudgeJson(text);
-    return {
-      pass: parsed.pass === true,
-      reasoning: typeof parsed.reasoning === "string" ? parsed.reasoning : "",
-      judge
-    };
+    const verdict = judgeVerdict(result.completion.text);
+    if (verdict === void 0) {
+      return {
+        pass: false,
+        reasoning: "Judge reply carried no verdict (no boolean `pass`). The verdict is unknown, so this check is recorded as a judge error, not a verdict. The raw reply is on the judge metadata.",
+        judge,
+        unavailable: true
+      };
+    }
+    return { ...verdict, judge };
   });
 }
 function transportFailure(prefix, error) {
@@ -925,6 +1451,29 @@ function transportFailure(prefix, error) {
     retryable: !timedOut
   };
 }
+function buildJudgePromptParts(args) {
+  const deliverableText = `Values to evaluate:
+${formatJudgeValues(args.values)}`;
+  const { briefingText, instructionText } = assembleBriefing(args);
+  const secondJudgeProjected = args.secondJudgeValue !== void 0;
+  const secondJudgeValues = args.secondJudgeValue ?? args.values;
+  const secondJudgeDeliverableText = `Values to evaluate:
+${formatJudgeValues(secondJudgeValues)}`;
+  return {
+    briefingText,
+    instructionText,
+    systemPromptText: `${briefingText}
+
+${deliverableText}`,
+    deliverableText,
+    secondJudgeState: `${briefingText}
+
+${secondJudgeDeliverableText}
+
+${instructionText}`,
+    secondJudgeProjected
+  };
+}
 function assembleBriefing(args) {
   if (!args.prompt) {
     return {
@@ -953,6 +1502,55 @@ ${args.instruction}`
   };
 }
 
+// src/agent-task/checks/judge-cascade.ts
+var CASCADE_CONFIDENCE_THRESHOLD = 0.95;
+function isCascadeActive(effective) {
+  return effective?.mode === "cascade" && resolveSecondJudgeModel() !== void 0;
+}
+async function cascadePreflight(args) {
+  const model = resolveSecondJudgeModel();
+  if (model === void 0) return { kind: "off" };
+  const parts = buildJudgePromptParts({
+    values: args.values,
+    instruction: args.instruction,
+    ...args.effective.prompt ? { prompt: args.effective.prompt } : {},
+    ...args.context ? { context: args.context } : {},
+    ...args.secondJudgeValue !== void 0 ? { secondJudgeValue: args.secondJudgeValue } : {}
+  });
+  const evidence = await callSecondJudge({
+    state: parts.secondJudgeState,
+    model,
+    baseURL: resolveSecondJudgeBaseURL(defaultJudgeBaseURL(args.effective.baseURL)),
+    apiKey: resolveSecondJudgeAPIKey(defaultJudgeAPIKey(args.effective.apiKey)),
+    ...parts.secondJudgeProjected ? { projected: true } : {}
+  });
+  return { kind: "ran", evidence, parts };
+}
+function cascadeDecides(evidence) {
+  return evidence !== void 0 && (evidence.choice === "pass" || evidence.choice === "fail") && typeof evidence.confidence === "number" && evidence.confidence >= CASCADE_CONFIDENCE_THRESHOLD && evidence.error === void 0 && evidence.skipped === void 0 && evidence.projected !== true;
+}
+function cascadeVerdict(evidence, parts) {
+  const pass = evidence.choice === "pass";
+  return {
+    pass,
+    reasoning: `Verdict by second judge (cascade): ${evidence.choice} \xB7 confidence ${evidence.confidence}` + (evidence.passProbability !== void 0 ? ` \xB7 p(pass) ${evidence.passProbability}` : "") + `. Primary judge not called.`,
+    judge: {
+      model: evidence.model,
+      prompt: { system: parts.systemPromptText, user: parts.instructionText },
+      response: JSON.stringify({
+        choice: evidence.choice,
+        probabilities: { pass: evidence.passProbability },
+        confidence: evidence.confidence
+      }),
+      ...evidence.inputTokens !== void 0 ? { tokens: { input: evidence.inputTokens, output: 0 } } : {},
+      ...evidence.latencyMs !== void 0 ? { latency_ms: evidence.latencyMs } : {},
+      ...evidence.costUsd !== void 0 ? { cost: evidence.costUsd } : {},
+      secondJudge: evidence,
+      verdict_by: "second-judge"
+    }
+  };
+}
+
 // src/agent-task/checks/agent-session.ts
 import { createHash as createHash3 } from "crypto";
 
@@ -1362,6 +1960,25 @@ function isAbortError(error) {
   const name = error instanceof Error ? error.name : "";
   return name === "TimeoutError" || name === "AbortError" || name === "ResponseAborted";
 }
+var LEADING_PCRE_FLAGS = /^\(\?([a-z]+)\)/;
+var PCRE_FLAGS_JS_SUPPORTS = /* @__PURE__ */ new Set(["i", "m", "s"]);
+function stripLeadingPcreFlags(pattern) {
+  const m = LEADING_PCRE_FLAGS.exec(pattern);
+  if (!m) return { pattern, flags: "gim" };
+  const unsupported = [...m[1]].filter((f) => !PCRE_FLAGS_JS_SUPPORTS.has(f));
+  if (unsupported.length > 0) {
+    throw new Error(`leading flag group (?${m[1]}) \u2014 JS RegExp has no equivalent for ${unsupported.join(", ")}`);
+  }
+  return {
+    pattern: pattern.slice(m[0].length),
+    flags: m[1].includes("s") ? "gims" : "gim"
+  };
+}
+var UNSUPPORTED_PCRE_CONSTRUCTS = /\\[AQZz]/;
+function rejectUnsupportedPcreConstructs(pattern) {
+  const m = UNSUPPORTED_PCRE_CONSTRUCTS.exec(pattern);
+  return m ? `unsupported PCRE construct ${m[0]} \u2014 JS RegExp has no equivalent; anchor with ^ / $ (the search is multiline) or rewrite the pattern` : void 0;
+}
 function aggregateUsage(steps) {
   return steps.reduce(
     (acc, s) => ({
@@ -1377,14 +1994,15 @@ function recordedCost(steps) {
   return known.reduce((a, s) => a + s.tokens?.cost, 0);
 }
 function extractVerdict(steps) {
-  const call = steps.flatMap((s) => s.tool_calls ?? []).find((c) => c.name === "finish_verdict");
-  if (!call?.input) return void 0;
-  try {
-    const args = JSON.parse(call.input);
-    if (typeof args.reasoning === "string" && args.reasoning.length > 0 && typeof args.pass === "boolean") {
-      return { reasoning: args.reasoning, pass: args.pass };
+  for (const call of steps.flatMap((s) => s.tool_calls ?? [])) {
+    if (call.name !== "finish_verdict" || !call.input) continue;
+    try {
+      const args = JSON.parse(call.input);
+      if (typeof args.reasoning === "string" && args.reasoning.length > 0 && typeof args.pass === "boolean") {
+        return { reasoning: args.reasoning, pass: args.pass };
+      }
+    } catch {
     }
-  } catch {
   }
   return void 0;
 }
@@ -1401,7 +2019,15 @@ function buildEvidenceTools(args) {
     });
     return ledger.readBytesUsed > budget.maxReadBytes ? overflow() : null;
   };
-  const span = (name, input, fn) => tracer ? tracer.traceTool(name, input, fn) : fn();
+  const dedupeCache = /* @__PURE__ */ new Map();
+  const span = (name, input, fn) => {
+    const key = `${stepIndexOf()}|${name}|${JSON.stringify(input ?? {})}`;
+    const cached = dedupeCache.get(key);
+    if (cached) return cached;
+    const execution = tracer ? tracer.traceTool(name, input, fn) : fn();
+    dedupeCache.set(key, execution);
+    return execution;
+  };
   const tools = {
     read_deliverable: tool({
       description: `Read one of this run's deliverables by name, with optional offset/limit for pagination (max ${MAX_READ_WINDOW} bytes per call).`,
@@ -1432,7 +2058,7 @@ function buildEvidenceTools(args) {
       }
     }),
     search_deliverable: tool({
-      description: "Regex-search one of this run's deliverables; returns up to 8 matches with surrounding context. Cheaper than reading a large deliverable end to end \u2014 use it to locate the relevant part first.",
+      description: "Regex-search one of this run's deliverables (case-insensitive; ^ and $ match line starts/ends); returns up to 8 matches with surrounding context. Cheaper than reading a large deliverable end to end \u2014 use it to locate the relevant part first.",
       inputSchema: z.object({ name: z.string(), pattern: z.string() }),
       execute: async (input) => {
         const { name, pattern } = input;
@@ -1445,12 +2071,22 @@ function buildEvidenceTools(args) {
           if (pattern.length > SEARCH_MAX_PATTERN) {
             return { error: `pattern too long (max ${SEARCH_MAX_PATTERN} chars)` };
           }
-          let re;
+          const unsupported = rejectUnsupportedPcreConstructs(pattern);
+          if (unsupported) return { error: unsupported };
+          let translated;
           try {
-            re = new RegExp(pattern, "gi");
+            translated = stripLeadingPcreFlags(pattern);
           } catch (error) {
             return { error: `invalid regex: ${error instanceof Error ? error.message : String(error)}` };
           }
+          let re;
+          try {
+            re = new RegExp(translated.pattern, translated.flags);
+          } catch (error) {
+            return {
+              error: `invalid regex: ${error instanceof Error ? error.message : String(error)} \u2014 patterns compile as case-insensitive multiline; leading PCRE flags like (?i) are stripped automatically`
+            };
+          }
           const content = renderValue2(evidence.deliverables[name]).slice(0, SEARCH_SCAN_LIMIT);
           const hits = [];
           let m;
@@ -1846,7 +2482,12 @@ function createAgentMethod(rec, judgeConfig, judgeScope, evidence, judgeTracer,
       const detail = result.outcome === "error" ? `agentic judge session errored before verdicting: ${result.error ?? "unknown error"}` : `agentic judge session ended without a verdict (budget exhausted after ${result.session.usage?.steps ?? "?"} steps; last tool: ${result.session.steps?.at(-1)?.tool_calls?.map((c) => c.name).join(", ") ?? "none"})`;
       const agreed = opts?.expect === void 0 ? result.verdict?.pass ?? false : result.verdict ? result.verdict.pass === (opts.expect === "pass") : false;
       const reasoning = opts?.expect === void 0 || agreed || !result.verdict ? result.verdict?.reasoning ?? detail : `judge ${result.verdict.pass ? "PASSed" : "FAILed"} where ground truth is ${opts.expect.toUpperCase()} \u2014 judge reasoning: ${result.verdict.reasoning}`;
-      rec.record(label, agreed, reasoning, {
+      const consultedEvidence = (result.session.evidence?.length ?? 0) > 0 || exhibits.length > 0 || (result.session.steps?.some(
+        (s) => s.tool_calls?.some((c) => c.name === "get_trace" || c.name === "list_runs" || c.name === "get_run")
+      ) ?? false);
+      const readNothing = result.verdict !== void 0 && !consultedEvidence && evidence !== void 0 && Object.keys(evidence.deliverables).length > 0;
+      const recorded = readNothing ? `${reasoning} \u2014 [vacuous verdict: the session consulted no run evidence before deciding]` : reasoning;
+      rec.record(label, agreed, recorded, {
         evaluator_type: "agent",
         judge,
         expected: instruction,
@@ -1873,7 +2514,8 @@ function resolveJudgeConfig(judgeConfig, override) {
     model,
     baseURL: override?.baseURL ?? judgeConfig?.baseURL,
     apiKey: override?.apiKey ?? judgeConfig?.apiKey,
-    prompt: override?.prompt ?? judgeConfig?.prompt
+    prompt: override?.prompt ?? judgeConfig?.prompt,
+    mode: override?.mode ?? judgeConfig?.mode
   };
 }
 var TEST_METHOD_NAMES = [
@@ -1890,6 +2532,8 @@ var TEST_METHOD_NAMES = [
   "maxDurationMs",
   "maxTokens",
   "minTokens",
+  "steerDelivered",
+  "afterSteer",
   "assert",
   "check",
   "judge",
@@ -1912,6 +2556,58 @@ function trackPending(rec, method) {
     return promise;
   });
 }
+function createSteerAssertions(view, rec, makeNested) {
+  const findSteer = (n, id) => {
+    const steers = view.steers;
+    if (steers.length === 0) {
+      rec.record(
+        id,
+        false,
+        "steering evidence unavailable \u2014 no task.steer events in this trace",
+        { expected: `steer ${n} delivered and consumed`, received: "no steering evidence" }
+      );
+      return void 0;
+    }
+    const steer2 = steers.find((s) => s.number === n);
+    if (!steer2) {
+      rec.record(
+        id,
+        false,
+        `no steer number ${n} in this trace (found: ${steers.map((s) => s.number).join(", ")})`,
+        { expected: `steer ${n} exists`, received: steers.map((s) => s.number).join(", ") || "none" }
+      );
+    }
+    return steer2;
+  };
+  return {
+    steerDelivered(n) {
+      const steer2 = findSteer(n, `steerDelivered(${n})`);
+      if (!steer2) return;
+      if (steer2.status !== "delivered") {
+        const why = steer2.reason ? ` \u2014 ${steer2.reason}` : "";
+        rec.record(`steerDelivered(${n})`, false, `steer ${n} was ${steer2.status}${why}`, {
+          expected: "delivered",
+          received: steer2.status
+        });
+        return;
+      }
+      const consumed = view.snapshot.observations.some(
+        (o) => o.type === "GENERATION" && steer2.spanStartedAt != null && o.startedAt != null && (o.startedAt > steer2.spanStartedAt || o.startedAt === steer2.spanStartedAt && o.spanId > steer2.spanId)
+      );
+      rec.record(
+        `steerDelivered(${n})`,
+        consumed,
+        consumed ? "" : `steer ${n} was delivered but no generation observation started after it \u2014 the harness queued the message, no model call demonstrably consumed it`,
+        { expected: `\u22651 generation after steer ${n}`, received: consumed ? "1+" : "0" }
+      );
+    },
+    afterSteer(n, fn) {
+      const steer2 = findSteer(n, `afterSteer(${n})`);
+      if (!steer2) return;
+      fn(makeNested(view.windowAfterSteer(n)));
+    }
+  };
+}
 function createJudgeMethod(rec, judgeConfig, judgeScope, judgeTracer) {
   return async (values, instruction, opts) => {
     const label = opts?.label ?? "judge";
@@ -1931,6 +2627,52 @@ function createJudgeMethod(rec, judgeConfig, judgeScope, judgeTracer) {
     const context2 = judgeScopeToContext(judgeScope);
     const judgeServing = servingHostFromBaseURL(effective.baseURL);
     const secondJudgeValue = opts?.secondJudgeValue;
+    let prefetchedSecondJudge;
+    if (isCascadeActive(effective)) {
+      let preflight;
+      try {
+        preflight = await cascadePreflight({
+          values: valueArray,
+          instruction,
+          effective,
+          ...context2 ? { context: context2 } : {},
+          ...secondJudgeValue !== void 0 ? {
+            secondJudgeValue: Array.isArray(secondJudgeValue) ? secondJudgeValue : [secondJudgeValue]
+          } : {}
+        });
+      } catch (error) {
+        rec.record(
+          label,
+          false,
+          `judge failed: ${error instanceof Error ? error.message : String(error)}`,
+          {
+            evaluator_type: "llm",
+            expected: instruction,
+            received: valueArray.length === 1 ? valueArray[0] : valueArray,
+            location,
+            outcome: "error"
+          }
+        );
+        return;
+      }
+      if (preflight.kind === "ran" && cascadeDecides(preflight.evidence)) {
+        const { pass, reasoning, judge } = cascadeVerdict(
+          preflight.evidence,
+          preflight.parts
+        );
+        const agreed = opts?.expect === void 0 ? pass : pass === (opts.expect === "pass");
+        const recordedReasoning = opts?.expect === void 0 || agreed ? reasoning : `second judge ${pass ? "PASSed" : "FAILed"} where ground truth is ${opts.expect.toUpperCase()} \u2014 ${reasoning}`;
+        rec.record(label, agreed, recordedReasoning, {
+          evaluator_type: "llm",
+          judge,
+          expected: instruction,
+          received: valueArray.length === 1 ? valueArray[0] : valueArray,
+          location
+        });
+        return;
+      }
+      if (preflight.kind === "ran") prefetchedSecondJudge = preflight.evidence;
+    }
     const call = () => callJudge({
       values: valueArray,
       instruction,
@@ -1939,6 +2681,7 @@ function createJudgeMethod(rec, judgeConfig, judgeScope, judgeTracer) {
       apiKey: effective.apiKey,
       prompt: effective.prompt,
       ...context2 ? { context: context2 } : {},
+      ...prefetchedSecondJudge ? { prefetchedSecondJudge } : {},
       ...secondJudgeValue !== void 0 ? {
         secondJudgeValue: Array.isArray(secondJudgeValue) ? secondJudgeValue : [secondJudgeValue]
       } : {}
@@ -2211,6 +2954,19 @@ function createTraceTestContext(view, rec, judgeConfig, judgeScope, agentEvidenc
         received: pass ? "true" : "false"
       });
     },
+    ...createSteerAssertions(
+      view,
+      rec,
+      (window) => createTraceTestContext(
+        window,
+        rec,
+        judgeConfig,
+        judgeScope,
+        agentEvidence,
+        judgeTracer,
+        judgeTools
+      )
+    ),
     check(value, matcher, label) {
       const pass = matcher.test(value);
       rec.record(
@@ -2887,6 +3643,29 @@ function resolveTurn(adapterTurn, taskTurn) {
   return resolved;
 }
 
+// src/agent-task/steer.ts
+var STEERS_KEY = /* @__PURE__ */ Symbol.for("@apo-ai/sdk/agent-task/task-steers");
+function steer(spec) {
+  if (spec.turn !== void 0 && (!Number.isInteger(spec.turn) || spec.turn < 1)) {
+    throw new Error(`steer: turn must be a positive integer, got ${spec.turn}`);
+  }
+  const count = spec.when === "runStart" ? void 0 : "toolResults" in spec.when ? ["toolResults", spec.when.toolResults] : ["assistantReply", spec.when.assistantReply];
+  if (count !== void 0 && (!Number.isInteger(count[1]) || count[1] < 1)) {
+    throw new Error(`steer: ${count[0]} must be a positive integer, got ${count[1]}`);
+  }
+  const registry2 = globalThis[STEERS_KEY];
+  const list = Array.isArray(registry2) ? registry2 : [];
+  list.push(spec);
+  globalThis[STEERS_KEY] = list;
+}
+function getTaskSteers() {
+  const registry2 = globalThis[STEERS_KEY];
+  return Array.isArray(registry2) ? [...registry2] : [];
+}
+function resetTaskSteers() {
+  delete globalThis[STEERS_KEY];
+}
+
 // src/agent-task/task/loadTask.ts
 async function loadTask(taskDir) {
   const absoluteDir = resolve2(taskDir);
@@ -2959,6 +3738,7 @@ async function loadTaskDefinition(taskFilePath) {
     resetTaskRegistry();
     resetFlowChecks();
     resetTaskTurn();
+    resetTaskSteers();
     const loaded = await import(moduleUrl);
     const registeredTask = getRegisteredTask();
     const task2 = registeredTask ?? loaded.default;
@@ -3822,12 +4602,13 @@ function sleep(ms) {
 
 // src/agent-task/checks/agent-history.ts
 function createBackendReaderFromEnv(env = process.env) {
+  const apiKey = env.APO_API_KEY;
   const token = env.APO_AUTH_TOKEN;
   const publicKey = env.APO_PUBLIC_KEY;
   const secretKey = env.APO_SECRET_KEY;
-  const headers = token ? { Authorization: `Bearer ${token}` } : publicKey && secretKey ? { Authorization: `Basic ${Buffer.from(`${publicKey}:${secretKey}`).toString("base64")}` } : void 0;
+  const headers = apiKey ? { Authorization: `Bearer ${apiKey}` } : token ? { Authorization: `Bearer ${token}` } : publicKey && secretKey ? { Authorization: `Basic ${Buffer.from(`${publicKey}:${secretKey}`).toString("base64")}` } : void 0;
   if (!headers) return void 0;
-  const endpoint = env.APO_BACKEND_URL ?? env.AGENT_TASK_TRACE_ENDPOINT ?? "http://127.0.0.1:8000";
+  const endpoint = env.APO_BACKEND_URL ?? "http://127.0.0.1:8000";
   return {
     async get(path) {
       const res = await fetch(`${endpoint.replace(/\/$/, "")}/v1${path}`, { headers });
@@ -3841,10 +4622,23 @@ function createBackendReaderFromEnv(env = process.env) {
 function freezeHistoryPlane(args) {
   const { reader, taskId, selfRunId } = args;
   const detailCache = /* @__PURE__ */ new Map();
+  const listByTaskId = async (id) => await reader.get(
+    `/agent-task-runs?task_id=${encodeURIComponent(id)}&limit=50`
+  );
   const loadRuns = (async () => {
-    const raw = await reader.get(
-      `/agent-task-runs?task_id=${encodeURIComponent(taskId)}&limit=50`
-    );
+    let raw = await listByTaskId(taskId);
+    if ((raw ?? []).length === 0 && selfRunId) {
+      try {
+        const self = await reader.get(
+          `/agent-task-runs/${encodeURIComponent(selfRunId)}`
+        );
+        const canonical = self?.task_id;
+        if (typeof canonical === "string" && canonical !== taskId) {
+          raw = await listByTaskId(canonical);
+        }
+      } catch {
+      }
+    }
     return (raw ?? []).map(
       (r) => ({
         id: String(r.id),
@@ -3908,7 +4702,9 @@ async function freezeHistoryPlaneFromEnv(taskId, env = process.env) {
       taskId,
       ...env.AGENT_TASK_RUN_ID ? { selfRunId: env.AGENT_TASK_RUN_ID } : {}
     });
-  } catch {
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    console.warn(`apo: judge history plane unavailable \u2014 ${reason}`);
     return void 0;
   }
 }
@@ -5167,6 +5963,7 @@ async function runTurnLoop(loaded, options, session, trace2, rawTrace) {
   const { task: task2, adapter, files, checksPath, inlineChecks } = loaded;
   if (!inlineChecks && checksPath) {
     resetTaskTurn();
+    resetTaskSteers();
     resetFlowChecks();
     await loadChecksModule(checksPath);
   }
@@ -5174,14 +5971,32 @@ async function runTurnLoop(loaded, options, session, trace2, rawTrace) {
   resetTaskTurn();
   const turnFn = resolveTurn(adapter.turn, taskTurn);
   if (!turnFn) return [];
+  const steerSpecs = getTaskSteers();
+  resetTaskSteers();
+  if (steerSpecs.length > 0 && typeof session.steer !== "function") {
+    throw new AgentTaskRunError(
+      `Task "${task2.id}" registers ${steerSpecs.length} steer(s) but adapter "${adapter.name}" does not implement session.steer(). Implement steer() on the adapter session, or remove the steer() registrations.`,
+      {}
+    );
+  }
+  const turnSpanIds = /* @__PURE__ */ new Map();
+  const scheduler = createSteerScheduler({
+    specs: steerSpecs,
+    session,
+    trace: trace2,
+    turnSpanId: (turnNumber) => turnSpanIds.get(turnNumber),
+    onSteer: options?.onSteer
+  });
   const taskFiles = new TaskFiles(files);
   const turnTranscript = [];
   const transcriptTurns = [];
   let lastTurnResponse;
+  let lastTurnNumber = 0;
   const maxTurns = options?.maxTurnsOverride ?? task2.maxTurns ?? 10;
   for (let turnNum = 1; turnNum <= maxTurns; turnNum++) {
     const userTurn = await turnFn({ files: taskFiles, transcript: turnTranscript });
     if (userTurn === null || userTurn === void 0) break;
+    await scheduler.onTurnStart(turnNum);
     const result = await trace2.step(
       {
         step_name: "task.turn",
@@ -5192,15 +6007,29 @@ async function runTurnLoop(loaded, options, session, trace2, rawTrace) {
       // processor captures parent under the turn span, not the run root —
       // turn-scoped assertions (t.maxTokens({ turn })) walk that chain.
       async (spanId) => {
+        turnSpanIds.set(turnNum, spanId);
         const run = getActiveApoRun();
         const send = () => session.sendUserTurn(userTurn, {
           trace: trace2,
           turnNumber: turnNum,
-          parentSpanId: spanId
+          parentSpanId: spanId,
+          // Progress events drive the steer scheduler. Fire-and-forget:
+          // the adapter never waits on steering, and scheduler errors are
+          // contained (they must not break the agent's turn).
+          notifyAgentEvent: (event) => {
+            void scheduler.onProgressEvent(turnNum, event).catch((error) => {
+              console.error(
+                "[AgentTask] Steer scheduler error:",
+                error instanceof Error ? error.message : String(error)
+              );
+            });
+          }
         });
         return run ? withApoRun({ ...run, parentSpanId: spanId, turnNumber: turnNum }, send) : send();
       }
     );
+    await scheduler.onTurnEnd(turnNum);
+    const turnSteers = scheduler.recordsByTurn().get(turnNum);
     turnTranscript.push({
       turnNumber: turnNum,
       input: userTurn,
@@ -5209,11 +6038,14 @@ async function runTurnLoop(loaded, options, session, trace2, rawTrace) {
     transcriptTurns.push({
       turnNumber: turnNum,
       userAction: userTurn,
-      agentResponse: result.response
+      agentResponse: result.response,
+      ...turnSteers !== void 0 && turnSteers.length > 0 ? { steers: turnSteers } : {}
     });
     options?.onTurn?.(turnNum, userTurn, result.response);
     lastTurnResponse = result.response;
+    lastTurnNumber = turnNum;
   }
+  await scheduler.onRunEnd(lastTurnNumber);
   if (lastTurnResponse !== void 0) {
     rawTrace.endRoot({ output: { response: lastTurnResponse } });
   }
@@ -5741,6 +6573,9 @@ function createOtelAgentTaskTraceClient(config) {
         params.reasoning_tokens
       );
     }
+    if (params.served_model) {
+      active.span.setAttribute("gen_ai.response.model", params.served_model);
+    }
     if (params.status_message) {
       active.span.setAttribute("apo.status_message", params.status_message);
     }
@@ -6079,7 +6914,12 @@ function resolveJudgeFromEnv() {
   return {
     model,
     baseURL: openRouterModel ? process.env.OPENROUTER_BASE_URL : process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1",
-    apiKey: openRouterModel ? process.env.OPENROUTER_API_KEY : process.env.OPENAI_API_KEY
+    apiKey: openRouterModel ? process.env.OPENROUTER_API_KEY : process.env.OPENAI_API_KEY,
+    // "cascade" turns on second-judge-first judging (a confident decision
+    // model verdict stands without calling the primary judge); any other
+    // value is ignored so a typo degrades to the default dual mode, never
+    // an error.
+    ...process.env.APO_JUDGE_MODE?.trim() === "cascade" ? { mode: "cascade" } : {}
   };
 }
 async function runTaskDir(taskDir, options) {
@@ -6353,6 +7193,7 @@ export {
   ApoSpanProcessor,
   FlowView,
   JUDGE_SEGMENT_LIMIT,
+  NO_CHECKS_REGISTERED_MESSAGE,
   RECEIVED_VALUE_LIMIT,
   RejudgeError,
   TEST_METHOD_NAMES,
@@ -6381,6 +7222,7 @@ export {
   fromAnthropicMessages,
   fromOpenAIMessages,
   getActiveApoRun,
+  getTaskSteers,
   getTaskTurn,
   includes,
   isFileArtifact,
@@ -6399,6 +7241,7 @@ export {
   resetApoTracing,
   resetFlowChecks,
   resetTaskRegistry,
+  resetTaskSteers,
   resetTaskTurn,
   resolveMcpServerPaths,
   resolveOtlpTracesUrl,
@@ -6407,8 +7250,11 @@ export {
   runTask,
   runTaskDir,
   satisfies,
+  secondJudgeFacts,
+  secondJudgeTakeaway,
   sha256Hex2 as sha256Hex,
   similarity,
+  steer,
   task,
   defineCheck as test,
   transcriptSessionToOtlp,