@apo-ai/sdk 0.10.1 → 0.11.0

package/dist/agent-task/public.js

@@ -24,13 +24,225 @@ import {
   servingHostFromBaseURL
 } from "../chunk-Z64A566W.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;
@@ -383,6 +645,33 @@ function levenshtein(a, b) {
 import { createHash } from "crypto";
 
 // 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 +750,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 +785,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 +828,9 @@ 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 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 +841,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 +916,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;
@@ -735,33 +1066,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 +1109,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 +1148,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,7 +1162,8 @@ ${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 } : {}
         };
       }
       try {
@@ -864,17 +1195,21 @@ ${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);
+    }
+    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" && first.kind === "unavailable") {
           result = {
             ...result,
@@ -904,12 +1239,16 @@ ${instructionText}`,
         unavailable: true
       };
     }
-    const parsed = parseJudgeJson(text);
-    return {
-      pass: parsed.pass === true,
-      reasoning: typeof parsed.reasoning === "string" ? parsed.reasoning : "",
-      judge
-    };
+    const verdict = judgeVerdict(text);
+    if (verdict === void 0) {
+      return {
+        pass: false,
+        reasoning: "Judge reply carried no verdict (no boolean `pass`) on two draws. 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 +1264,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 +1315,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 +1773,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 +1807,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 +1832,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 +1871,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,11 +1884,16 @@ function buildEvidenceTools(args) {
           if (pattern.length > SEARCH_MAX_PATTERN) {
             return { error: `pattern too long (max ${SEARCH_MAX_PATTERN} chars)` };
           }
+          const unsupported = rejectUnsupportedPcreConstructs(pattern);
+          if (unsupported) return { error: unsupported };
           let re;
           try {
-            re = new RegExp(pattern, "gi");
+            const stripped = stripLeadingPcreFlags(pattern);
+            re = new RegExp(stripped.pattern, stripped.flags);
           } catch (error) {
-            return { error: `invalid regex: ${error instanceof Error ? error.message : String(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 = [];
@@ -1846,7 +2290,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 +2322,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 +2340,8 @@ var TEST_METHOD_NAMES = [
   "maxDurationMs",
   "maxTokens",
   "minTokens",
+  "steerDelivered",
+  "afterSteer",
   "assert",
   "check",
   "judge",
@@ -1912,6 +2364,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 +2435,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 +2489,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 +2762,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 +3451,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 +3546,7 @@ async function loadTaskDefinition(taskFilePath) {
     resetTaskRegistry();
     resetFlowChecks();
     resetTaskTurn();
+    resetTaskSteers();
     const loaded = await import(moduleUrl);
     const registeredTask = getRegisteredTask();
     const task2 = registeredTask ?? loaded.default;
@@ -5167,6 +5755,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 +5763,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 +5799,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 +5830,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 } });
   }
@@ -6079,7 +6703,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 +6982,7 @@ export {
   ApoSpanProcessor,
   FlowView,
   JUDGE_SEGMENT_LIMIT,
+  NO_CHECKS_REGISTERED_MESSAGE,
   RECEIVED_VALUE_LIMIT,
   RejudgeError,
   TEST_METHOD_NAMES,
@@ -6381,6 +7011,7 @@ export {
   fromAnthropicMessages,
   fromOpenAIMessages,
   getActiveApoRun,
+  getTaskSteers,
   getTaskTurn,
   includes,
   isFileArtifact,
@@ -6399,6 +7030,7 @@ export {
   resetApoTracing,
   resetFlowChecks,
   resetTaskRegistry,
+  resetTaskSteers,
   resetTaskTurn,
   resolveMcpServerPaths,
   resolveOtlpTracesUrl,
@@ -6407,8 +7039,11 @@ export {
   runTask,
   runTaskDir,
   satisfies,
+  secondJudgeFacts,
+  secondJudgeTakeaway,
   sha256Hex2 as sha256Hex,
   similarity,
+  steer,
   task,
   defineCheck as test,
   transcriptSessionToOtlp,