@apo-ai/sdk 0.7.1 → 0.8.0

package/dist/agent-task/public.js

@@ -8,18 +8,18 @@ import {
   resetApoTracing,
   withApoRun,
   withApoRunSync
-} from "../chunk-GETY34VI.js";
+} from "../chunk-IPQ6IIEG.js";
 import {
   createApoTracer
-} from "../chunk-QHRWPVPZ.js";
-import "../chunk-HWZVL6TS.js";
+} from "../chunk-CKB3SUDO.js";
+import "../chunk-HLRXQAZ5.js";
 import {
   createApoOpenAI
-} from "../chunk-6ZRW5IW6.js";
+} from "../chunk-3B3L2H4Y.js";
 import {
   createApoAnthropic
-} from "../chunk-SZDSIPXC.js";
-import "../chunk-GDB6SDGN.js";
+} from "../chunk-43OI6GP7.js";
+import "../chunk-3OQ3JBFJ.js";
 
 // src/agent-task/trace-projection/view.ts
 function invocationOrderKey(obs) {
@@ -314,6 +314,12 @@ async function callSecondJudge(args) {
 }
 
 // src/agent-task/checks/judge.ts
+var JudgeUnavailableError = class extends Error {
+  constructor(message) {
+    super(message);
+    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}';
 function isJudgeVerdictFirstOverrideEnabled() {
@@ -389,7 +395,92 @@ function parseJudgeJson(raw) {
     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."
   };
 }
-var JUDGE_TIMEOUT_MS = 12e4;
+var JUDGE_TIMEOUT_MS = 3e5;
+var JUDGE_IDLE_TIMEOUT_MS = 9e4;
+var JUDGE_RETRY_DELAY_MS = 1e3;
+var JUDGE_RETRY_AFTER_CAP_MS = 2e4;
+var JUDGE_MIN_RETRY_BUDGET_MS = 6e4;
+function isRetryableStatus(status) {
+  return status === 429 || status >= 500;
+}
+function retryDelayMs(retryAfter) {
+  if (!retryAfter) return JUDGE_RETRY_DELAY_MS;
+  const seconds = Number(retryAfter);
+  const ms = Number.isFinite(seconds) ? seconds * 1e3 : Date.parse(retryAfter) - Date.now();
+  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) {
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.includes("text/event-stream")) {
+    const data = await response.json();
+    return {
+      text: data.choices?.[0]?.message?.content ?? "",
+      usage: data.usage,
+      finishReason: data.choices?.[0]?.finish_reason ?? void 0
+    };
+  }
+  let text = "";
+  let usage;
+  let finishReason;
+  let eventType = "message";
+  let dataLines = [];
+  let finished = false;
+  const dispatch = () => {
+    const payload = dataLines.join("\n").trim();
+    const type = eventType;
+    eventType = "message";
+    dataLines = [];
+    if (payload === "[DONE]") finished = true;
+    if (!payload || finished) return;
+    onData();
+    let chunk;
+    try {
+      chunk = JSON.parse(payload);
+    } catch {
+      chunk = void 0;
+    }
+    if (type === "error" || chunk?.error) {
+      const error = chunk?.error;
+      const message = typeof error === "string" ? error : error?.message ?? (chunk ? void 0 : payload);
+      throw new JudgeUnavailableError(`Judge stream error: ${message ?? "unknown"}`);
+    }
+    if (!chunk) return;
+    const choice = chunk.choices?.[0];
+    text += choice?.delta?.content ?? "";
+    if (choice?.finish_reason) finishReason = choice.finish_reason;
+    if (chunk.usage) usage = chunk.usage;
+  };
+  const handleLine = (line) => {
+    if (line === "") return dispatch();
+    if (line.startsWith(":")) return;
+    const colon = line.indexOf(":");
+    const field = colon === -1 ? line : line.slice(0, colon);
+    let value = colon === -1 ? "" : line.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "data") dataLines.push(value);
+    else if (field === "event") eventType = value;
+  };
+  const reader = response.body?.getReader();
+  if (!reader) return { text, usage, finishReason };
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split(/\r\n|\r(?!$)|\n/);
+    buffer = lines.pop() ?? "";
+    for (const line of lines) {
+      handleLine(line);
+      if (finished) return { text, usage, finishReason };
+    }
+  }
+  buffer += decoder.decode();
+  for (const line of buffer.split(/\r\n|\r|\n/)) if (line) handleLine(line);
+  dispatch();
+  return { text, usage, finishReason };
+}
 var prefixQueues = /* @__PURE__ */ new Map();
 function runWithSharedPrefix(key, task2) {
   const prev = prefixQueues.get(key) ?? Promise.resolve();
@@ -422,75 +513,155 @@ ${instructionText}`,
     apiKey: resolveSecondJudgeAPIKey(apiKey)
   }) : void 0;
   const cacheKey = `${args.model}\0${briefingText}\0${deliverableText}`;
-  return runWithSharedPrefix(cacheKey, async () => {
-    const startedAt = Date.now();
-    const response = await fetch(`${baseURL}/chat/completions`, {
-      method: "POST",
-      signal: AbortSignal.timeout(JUDGE_TIMEOUT_MS),
-      headers: {
-        "Content-Type": "application/json",
-        ...apiKey ? { Authorization: `Bearer ${apiKey}` } : {}
-      },
-      body: JSON.stringify({
-        model: args.model,
-        messages: [
+  const requestBody = (stream) => JSON.stringify({
+    model: args.model,
+    messages: [
+      {
+        role: "system",
+        content: [
+          { type: "text", text: briefingText },
           {
-            role: "system",
-            content: [
-              { type: "text", text: briefingText },
-              {
-                type: "text",
-                text: deliverableText,
-                cache_control: { type: "ephemeral" }
-              }
-            ]
+            type: "text",
+            text: deliverableText,
+            cache_control: { type: "ephemeral" }
+          }
+        ]
+      },
+      { role: "user", content: instructionText }
+    ],
+    temperature: 0,
+    response_format: { type: "json_object" },
+    ...stream ? { stream: true, stream_options: { include_usage: true } } : {}
+  });
+  const attempt = async (stream, deadline) => {
+    const controller = new AbortController();
+    const expire = (reason, name) => () => controller.abort(new DOMException(reason, name));
+    const total = setTimeout(
+      expire(`no complete response within ${JUDGE_TIMEOUT_MS / 1e3}s`, "TimeoutError"),
+      Math.max(deadline - Date.now(), 0)
+    );
+    const stalled = expire(`no data for ${JUDGE_IDLE_TIMEOUT_MS / 1e3}s`, "IdleTimeoutError");
+    let idle;
+    const onData = () => {
+      clearTimeout(idle);
+      idle = setTimeout(stalled, JUDGE_IDLE_TIMEOUT_MS);
+    };
+    try {
+      let response;
+      try {
+        response = await fetch(`${baseURL}/chat/completions`, {
+          method: "POST",
+          signal: controller.signal,
+          headers: {
+            "Content-Type": "application/json",
+            ...apiKey ? { Authorization: `Bearer ${apiKey}` } : {}
           },
-          { role: "user", content: instructionText }
-        ],
-        temperature: 0,
-        response_format: { type: "json_object" }
-      })
-    });
-    if (!response.ok) {
-      const body = await response.text().catch(() => "");
-      throw new Error(`Judge API ${response.status}: ${body.slice(0, 200)}`);
+          body: requestBody(stream)
+        });
+      } catch (error) {
+        return transportFailure("Judge request failed", controller.signal.reason ?? error);
+      }
+      if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        return {
+          kind: "unavailable",
+          error: new JudgeUnavailableError(`Judge API ${response.status}: ${body.slice(0, 200)}`),
+          retryable: isRetryableStatus(response.status),
+          ...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 } : {}
+        };
+      }
+      try {
+        return { kind: "completion", completion: await readCompletion(response, onData) };
+      } catch (error) {
+        return transportFailure("Judge response failed", controller.signal.reason ?? error);
+      }
+    } finally {
+      clearTimeout(total);
+      clearTimeout(idle);
+      controller.abort();
     }
-    const data = await response.json();
-    const text = data.choices?.[0]?.message?.content ?? "";
-    const outputTokens = data.usage?.completion_tokens;
-    const isEmpty = !text.trim();
-    const reportedZeroTokens = data.usage !== void 0 && outputTokens === 0;
-    if (isEmpty || reportedZeroTokens) {
+  };
+  const isTruncated = ({ text, usage, finishReason }) => {
+    if (!text.trim()) return true;
+    if (usage !== void 0 && usage.completion_tokens === 0) return true;
+    if (finishReason !== "length" && finishReason !== "content_filter" && finishReason !== "error") {
+      return false;
+    }
+    try {
+      JSON.parse(text);
+      return false;
+    } catch {
+      return true;
+    }
+  };
+  return runWithSharedPrefix(cacheKey, async () => {
+    const startedAt = Date.now();
+    const deadline = startedAt + JUDGE_TIMEOUT_MS;
+    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;
+    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 (deadline - Date.now() - delay >= JUDGE_MIN_RETRY_BUDGET_MS) {
+        if (streamRejected) stream = false;
+        await new Promise((resolve4) => setTimeout(resolve4, delay));
+        const first = result;
+        result = await attempt(stream, deadline);
+        if (result.kind === "unavailable" && first.kind === "unavailable") {
+          result = {
+            ...result,
+            error: new JudgeUnavailableError(
+              `${first.error.message} (retry: ${result.error.message})`
+            )
+          };
+        }
+      }
+    }
+    if (result.kind === "unavailable") throw result.error;
+    const { text, usage } = result.completion;
+    const judge = {
+      model: args.model,
+      contract: judgeContractInUse(),
+      prompt: { system: systemPromptText, user: instructionText },
+      response: text,
+      tokens: parseJudgeUsage(usage),
+      latency_ms: Date.now() - startedAt,
+      secondJudge: await secondJudgePromise
+    };
+    if (isTruncated(result.completion)) {
       return {
         pass: false,
-        reasoning: "Judge returned an empty or truncated response \u2014 likely a transient provider failure. The verdict is unknown, so this check is treated as a failure.",
-        judge: {
-          model: args.model,
-          contract: judgeContractInUse(),
-          prompt: { system: systemPromptText, user: instructionText },
-          response: text,
-          tokens: parseJudgeUsage(data.usage),
-          latency_ms: Date.now() - startedAt,
-          secondJudge: await secondJudgePromise
-        }
+        reasoning: "Judge returned an empty or truncated response \u2014 likely a transient provider failure. The verdict is unknown, so this check is recorded as a judge error, not a verdict.",
+        judge,
+        unavailable: true
       };
     }
     const parsed = parseJudgeJson(text);
     return {
       pass: parsed.pass === true,
       reasoning: typeof parsed.reasoning === "string" ? parsed.reasoning : "",
-      judge: {
-        model: args.model,
-        contract: judgeContractInUse(),
-        prompt: { system: systemPromptText, user: instructionText },
-        response: text,
-        tokens: parseJudgeUsage(data.usage),
-        latency_ms: Date.now() - startedAt,
-        secondJudge: await secondJudgePromise
-      }
+      judge
     };
   });
 }
+function transportFailure(prefix, error) {
+  if (error instanceof JudgeUnavailableError) {
+    return { kind: "unavailable", error, retryable: true };
+  }
+  const timedOut = error instanceof Error && error.name === "TimeoutError";
+  return {
+    kind: "unavailable",
+    error: new JudgeUnavailableError(
+      `${prefix}: ${error instanceof Error ? error.message : String(error)}`
+    ),
+    retryable: !timedOut
+  };
+}
 function assembleBriefing(args) {
   if (!args.prompt) {
     return {
@@ -521,6 +692,53 @@ ${args.instruction}`
 
 // src/agent-task/checks/agent-session.ts
 import { createHash } from "crypto";
+
+// src/agent-task/tracing.ts
+function createNoopAgentTaskTraceContext() {
+  const noopFn = async (fn) => fn();
+  return {
+    runId: "agent-task-untraced",
+    rootSpanId: "agent-task-untraced-root",
+    async step(options, fn) {
+      return fn(options.id ?? "agent-task-untraced-step");
+    },
+    recordEvent(options) {
+      return options.id ?? "agent-task-untraced-event";
+    },
+    endRoot() {
+    },
+    traceTool(_name, _params, fn) {
+      return noopFn(fn);
+    },
+    traceRetriever(_query, fn) {
+      return noopFn(fn);
+    },
+    traceChain(_name, fn) {
+      return noopFn(fn);
+    },
+    traceAgent(_name, fn) {
+      return noopFn(fn);
+    },
+    traceGuardrail(_name, fn) {
+      return noopFn(fn);
+    },
+    traceEmbedding(_model, _input, fn) {
+      return noopFn(fn);
+    },
+    async score(_params) {
+    },
+    createSpan(_options) {
+      return "agent-task-untraced-span";
+    },
+    endSpan(_spanId, _params) {
+    }
+  };
+}
+function isTraceableSpanId(spanId) {
+  return spanId !== void 0 && !spanId.startsWith("agent-task-untraced");
+}
+
+// src/agent-task/checks/agent-session.ts
 var DEFAULT_BUDGET = {
   maxTurns: 12,
   maxToolCalls: 24,
@@ -581,7 +799,7 @@ function extractVerdict(steps) {
   return void 0;
 }
 function buildEvidenceTools(args) {
-  const { z, tool, evidence, scope, budget, ledger, stepIndexOf, includeTrace } = args;
+  const { z, tool, evidence, scope, budget, ledger, stepIndexOf, includeTrace, includeHistory, tracer } = args;
   const budgetGuard = () => {
     ledger.toolCallsUsed += 1;
     if (ledger.toolCallsUsed > budget.maxToolCalls) {
@@ -600,6 +818,7 @@ function buildEvidenceTools(args) {
     });
     return ledger.readBytesUsed > budget.maxReadBytes ? overflow() : null;
   };
+  const span = (name, input, fn) => tracer ? tracer.traceTool(name, input, fn) : fn();
   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).`,
@@ -610,21 +829,23 @@ function buildEvidenceTools(args) {
       }),
       execute: async (input) => {
         const { name, offset, limit } = input;
-        const guard = budgetGuard();
-        if (guard) return { error: guard };
-        if (!Object.prototype.hasOwnProperty.call(evidence.deliverables, name)) {
-          return { error: `unknown deliverable: ${name}` };
-        }
-        const content = renderValue(evidence.deliverables[name]);
-        const slice = content.slice(offset, offset + limit);
-        const overflow = accountRead(
-          "read_deliverable",
-          JSON.stringify({ name, offset, limit }),
-          slice,
-          () => `read budget exhausted (${budget.maxReadBytes} bytes); call finish_verdict now`
-        );
-        if (overflow) return { error: overflow };
-        return { name, total_bytes: content.length, offset, returned: slice.length, content: slice };
+        return span("read_deliverable", input, async () => {
+          const guard = budgetGuard();
+          if (guard) return { error: guard };
+          if (!Object.prototype.hasOwnProperty.call(evidence.deliverables, name)) {
+            return { error: `unknown deliverable: ${name}` };
+          }
+          const content = renderValue(evidence.deliverables[name]);
+          const slice = content.slice(offset, offset + limit);
+          const overflow = accountRead(
+            "read_deliverable",
+            JSON.stringify({ name, offset, limit }),
+            slice,
+            () => `read budget exhausted (${budget.maxReadBytes} bytes); call finish_verdict now`
+          );
+          if (overflow) return { error: overflow };
+          return { name, total_bytes: content.length, offset, returned: slice.length, content: slice };
+        });
       }
     }),
     search_deliverable: tool({
@@ -632,49 +853,53 @@ function buildEvidenceTools(args) {
       inputSchema: z.object({ name: z.string(), pattern: z.string() }),
       execute: async (input) => {
         const { name, pattern } = input;
-        const guard = budgetGuard();
-        if (guard) return { error: guard };
-        if (!Object.prototype.hasOwnProperty.call(evidence.deliverables, name)) {
-          return { error: `unknown deliverable: ${name}` };
-        }
-        if (pattern.length > SEARCH_MAX_PATTERN) {
-          return { error: `pattern too long (max ${SEARCH_MAX_PATTERN} chars)` };
-        }
-        let re;
-        try {
-          re = new RegExp(pattern, "gi");
-        } catch (error) {
-          return { error: `invalid regex: ${error instanceof Error ? error.message : String(error)}` };
-        }
-        const content = renderValue(evidence.deliverables[name]).slice(0, SEARCH_SCAN_LIMIT);
-        const hits = [];
-        let m;
-        let execs = 0;
-        while ((m = re.exec(content)) && hits.length < SEARCH_HITS) {
-          if (++execs > SEARCH_MAX_EXEC) break;
-          const start = Math.max(0, m.index - SEARCH_CONTEXT);
-          hits.push({ at_byte: m.index, context: content.slice(start, m.index + m[0].length + SEARCH_CONTEXT) });
-          if (m.index === re.lastIndex) re.lastIndex++;
-        }
-        const served = JSON.stringify({ total_bytes: content.length, match_count: hits.length, matches: hits });
-        const overflow = accountRead(
-          "search_deliverable",
-          JSON.stringify({ name, pattern }),
-          served,
-          () => `read budget exhausted (${budget.maxReadBytes} bytes); call finish_verdict now`
-        );
-        if (overflow) return { error: overflow };
-        return { total_bytes: content.length, match_count: hits.length, matches: hits };
+        return span("search_deliverable", input, async () => {
+          const guard = budgetGuard();
+          if (guard) return { error: guard };
+          if (!Object.prototype.hasOwnProperty.call(evidence.deliverables, name)) {
+            return { error: `unknown deliverable: ${name}` };
+          }
+          if (pattern.length > SEARCH_MAX_PATTERN) {
+            return { error: `pattern too long (max ${SEARCH_MAX_PATTERN} chars)` };
+          }
+          let re;
+          try {
+            re = new RegExp(pattern, "gi");
+          } catch (error) {
+            return { error: `invalid regex: ${error instanceof Error ? error.message : String(error)}` };
+          }
+          const content = renderValue(evidence.deliverables[name]).slice(0, SEARCH_SCAN_LIMIT);
+          const hits = [];
+          let m;
+          let execs = 0;
+          while ((m = re.exec(content)) && hits.length < SEARCH_HITS) {
+            if (++execs > SEARCH_MAX_EXEC) break;
+            const start = Math.max(0, m.index - SEARCH_CONTEXT);
+            hits.push({ at_byte: m.index, context: content.slice(start, m.index + m[0].length + SEARCH_CONTEXT) });
+            if (m.index === re.lastIndex) re.lastIndex++;
+          }
+          const served = JSON.stringify({ total_bytes: content.length, match_count: hits.length, matches: hits });
+          const overflow = accountRead(
+            "search_deliverable",
+            JSON.stringify({ name, pattern }),
+            served,
+            () => `read budget exhausted (${budget.maxReadBytes} bytes); call finish_verdict now`
+          );
+          if (overflow) return { error: overflow };
+          return { total_bytes: content.length, match_count: hits.length, matches: hits };
+        });
       }
     }),
-    ...evidence.history ? {
+    ...includeHistory && evidence.history ? {
       list_runs: tool({
         description: "List runs of this task \u2014 id, status, pass/fail, model, check counts. The run under judgment is flagged; use get_run for a prior run's full check report.",
         inputSchema: z.object({}),
         execute: async () => {
-          const guard = budgetGuard();
-          if (guard) return { error: guard };
-          return evidence.history.runs;
+          return span("list_runs", {}, async () => {
+            const guard = budgetGuard();
+            if (guard) return { error: guard };
+            return evidence.history.runs;
+          });
         }
       }),
       get_run: tool({
@@ -682,18 +907,20 @@ function buildEvidenceTools(args) {
         inputSchema: z.object({ run_id: z.string() }),
         execute: async (input) => {
           const { run_id } = input;
-          const guard = budgetGuard();
-          if (guard) return { error: guard };
-          const detail = await evidence.history.getRun(run_id);
-          const served = JSON.stringify(detail);
-          const overflow = accountRead(
-            "get_run",
-            JSON.stringify({ run_id }),
-            served,
-            () => `read budget exhausted (${budget.maxReadBytes} bytes); call finish_verdict now`
-          );
-          if (overflow) return { error: overflow };
-          return detail;
+          return span("get_run", input, async () => {
+            const guard = budgetGuard();
+            if (guard) return { error: guard };
+            const detail = await evidence.history.getRun(run_id);
+            const served = JSON.stringify(detail);
+            const overflow = accountRead(
+              "get_run",
+              JSON.stringify({ run_id }),
+              served,
+              () => `read budget exhausted (${budget.maxReadBytes} bytes); call finish_verdict now`
+            );
+            if (overflow) return { error: overflow };
+            return detail;
+          });
         }
       })
     } : {},
@@ -701,13 +928,15 @@ function buildEvidenceTools(args) {
       description: "The task this run executed: id, description, deliverable names.",
       inputSchema: z.object({}),
       execute: async () => {
-        const guard = budgetGuard();
-        if (guard) return { error: guard };
-        return {
-          task_id: scope?.taskId,
-          description: scope?.taskDescription ?? "(unavailable)",
-          deliverables: Object.keys(evidence.deliverables)
-        };
+        return span("get_task_definition", {}, async () => {
+          const guard = budgetGuard();
+          if (guard) return { error: guard };
+          return {
+            task_id: scope?.taskId,
+            description: scope?.taskDescription ?? "(unavailable)",
+            deliverables: Object.keys(evidence.deliverables)
+          };
+        });
       }
     })
   };
@@ -717,21 +946,23 @@ function buildEvidenceTools(args) {
       inputSchema: z.object({ query: z.string().describe("substring filter on tool names; empty = all") }),
       execute: async (input) => {
         const { query } = input;
-        const guard = budgetGuard();
-        if (guard) return { error: guard };
-        const view = evidence.view;
-        if (!view) {
-          return {
-            status: "unsupported",
-            detail: "no trace projection exists for this run \u2014 judge on deliverables instead"
-          };
-        }
-        if (view.requireCapability("tools") !== "available") {
-          return { status: "unsupported", detail: "tool-call evidence is unavailable in this trace projection" };
-        }
-        const calls = view.toolCalls.filter((c) => query ? c.name.includes(query) : true).slice(0, 30).map((c) => ({ name: c.name, input: renderValue(c.input).slice(0, 200) }));
-        const reply = view.requireCapability("messages") === "available" && view.reply ? view.reply.slice(0, 1500) : void 0;
-        return { turns: view.turnCount, tool_calls: calls, ...reply !== void 0 ? { final_reply: reply } : {} };
+        return span("get_trace", input, async () => {
+          const guard = budgetGuard();
+          if (guard) return { error: guard };
+          const view = evidence.view;
+          if (!view) {
+            return {
+              status: "unsupported",
+              detail: "no trace projection exists for this run \u2014 judge on deliverables instead"
+            };
+          }
+          if (view.requireCapability("tools") !== "available") {
+            return { status: "unsupported", detail: "tool-call evidence is unavailable in this trace projection" };
+          }
+          const calls = view.toolCalls.filter((c) => query ? c.name.includes(query) : true).slice(0, 30).map((c) => ({ name: c.name, input: renderValue(c.input).slice(0, 200) }));
+          const reply = view.requireCapability("messages") === "available" && view.reply ? view.reply.slice(0, 1500) : void 0;
+          return { turns: view.turnCount, tool_calls: calls, ...reply !== void 0 ? { final_reply: reply } : {} };
+        });
       }
     });
   }
@@ -858,7 +1089,9 @@ async function runAgentSession(spec) {
     budget,
     ledger,
     stepIndexOf: () => liveSteps.length,
-    includeTrace: spec.tools?.trace !== false
+    includeTrace: spec.tools?.trace !== false,
+    includeHistory: spec.tools?.history !== false,
+    tracer: spec.tracer
   });
   const system = buildBriefing(spec.scope, spec.evidence, budget);
   const exhibitsBlock = spec.exhibits?.length ? "\n\nValues submitted for judgment:\n" + spec.exhibits.map((v, i) => `  [${i + 1}] ${renderValue(v).slice(0, RECORD_RESULT_LIMIT)}`).join("\n") : "";
@@ -918,7 +1151,7 @@ async function runAgentSession(spec) {
     latency_ms: Date.now() - started
   };
 }
-function createAgentMethod(rec, judgeConfig, judgeScope, evidence) {
+function createAgentMethod(rec, judgeConfig, judgeScope, evidence, judgeTracer) {
   return async (instruction, opts) => {
     const label = opts?.label ?? "agent";
     const location = rec.captureLocation();
@@ -934,18 +1167,54 @@ function createAgentMethod(rec, judgeConfig, judgeScope, evidence) {
       );
       return;
     }
+    const run = () => runAgentSession({
+      instruction,
+      model: effective.model,
+      baseURL: effective.baseURL,
+      apiKey: effective.apiKey,
+      evidence: evidence ?? { deliverables: {} },
+      scope: judgeScope,
+      exhibits,
+      tools: opts?.tools,
+      budget: opts?.budget,
+      tracer: judgeTracer
+    });
     try {
-      const result = await runAgentSession({
-        instruction,
-        model: effective.model,
-        baseURL: effective.baseURL,
-        apiKey: effective.apiKey,
-        evidence: evidence ?? { deliverables: {} },
-        scope: judgeScope,
-        exhibits,
-        tools: opts?.tools,
-        budget: opts?.budget
-      });
+      let sessionSpanId;
+      const result = await (judgeTracer ? judgeTracer.step(
+        {
+          step_name: `t.agent:${judgeScope?.checkName ?? label}`,
+          observation_type: "AGENT",
+          // The span carries the model + tokens so the backend prices the
+          // judge session and trace rollups count its spend (issue #288).
+          model: effective.model,
+          input: { model: effective.model, instruction },
+          usage: (r) => {
+            const usage = r?.usage;
+            return usage ? {
+              prompt_tokens: usage.input_tokens,
+              completion_tokens: usage.output_tokens
+            } : void 0;
+          },
+          summarize: (r) => {
+            const res = r;
+            const reasoning = res?.verdict?.reasoning?.slice(0, 2e3) ?? `session ended without a verdict (${res?.outcome ?? "unknown"})`;
+            return {
+              text: reasoning,
+              // reasoning-first, matching the judge response
+              // contract's default order (#163).
+              verdict: {
+                reasoning,
+                pass: res?.verdict?.pass ?? null
+              }
+            };
+          }
+        },
+        async (spanId) => {
+          sessionSpanId = spanId;
+          return run();
+        }
+      ) : run());
       const judge = {
         model: effective.model,
         temperature: 0,
@@ -956,7 +1225,8 @@ function createAgentMethod(rec, judgeConfig, judgeScope, evidence) {
         },
         ...result.cost !== void 0 ? { cost: result.cost } : {},
         latency_ms: result.latency_ms,
-        session: result.session
+        session: result.session,
+        ...isTraceableSpanId(sessionSpanId) ? { span_id: sessionSpanId } : {}
       };
       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"})`;
       rec.record(label, result.verdict?.pass ?? false, result.verdict?.reasoning ?? detail, {
@@ -1016,7 +1286,14 @@ function matchName(name, m) {
   if (m instanceof RegExp) return m.test(name);
   return m(name);
 }
-function createJudgeMethod(rec, judgeConfig, judgeScope) {
+function trackPending(rec, method) {
+  return ((...args) => {
+    const promise = method(...args);
+    rec.track(promise);
+    return promise;
+  });
+}
+function createJudgeMethod(rec, judgeConfig, judgeScope, judgeTracer) {
   return async (values, instruction, opts) => {
     const label = opts?.label ?? "judge";
     const location = rec.captureLocation();
@@ -1032,16 +1309,49 @@ function createJudgeMethod(rec, judgeConfig, judgeScope) {
       return;
     }
     const context2 = judgeScopeToContext(judgeScope);
-    try {
-      const { pass, reasoning, judge } = await callJudge({
-        values: valueArray,
-        instruction,
+    const call = () => callJudge({
+      values: valueArray,
+      instruction,
+      model: effective.model,
+      baseURL: effective.baseURL,
+      apiKey: effective.apiKey,
+      prompt: effective.prompt,
+      ...context2 ? { context: context2 } : {}
+    });
+    let judgeSpanId;
+    const traced = judgeTracer ? judgeTracer.step(
+      {
+        step_name: `judge:${judgeScope?.checkName ?? label}`,
+        // A single-shot judge call is an LLM generation — project it
+        // with the same observation semantics as the main agent's.
+        observation_type: "GENERATION",
+        // The span carries the model + tokens so the backend prices the
+        // judge call and trace rollups count its spend (issue #288).
         model: effective.model,
-        baseURL: effective.baseURL,
-        apiKey: effective.apiKey,
-        prompt: effective.prompt,
-        ...context2 ? { context: context2 } : {}
-      });
+        input: { model: effective.model, instruction },
+        summarize: (r) => {
+          const res = r;
+          return {
+            text: res?.reasoning?.slice(0, 2e3) ?? "",
+            verdict: {
+              reasoning: res?.reasoning?.slice(0, 2e3) ?? null,
+              pass: res?.pass ?? null
+            }
+          };
+        },
+        usage: (r) => {
+          const tokens = r?.judge?.tokens;
+          return tokens ? { prompt_tokens: tokens.input, completion_tokens: tokens.output } : void 0;
+        }
+      },
+      async (spanId) => {
+        judgeSpanId = spanId;
+        return call();
+      }
+    ) : call();
+    try {
+      const { pass, reasoning, judge, unavailable } = await traced;
+      if (isTraceableSpanId(judgeSpanId)) judge.span_id = judgeSpanId;
       rec.record(label, pass, reasoning, {
         evaluator_type: "llm",
         judge,
@@ -1050,7 +1360,8 @@ function createJudgeMethod(rec, judgeConfig, judgeScope) {
         // dashboard can render it with the right viewer — Markdown for
         // prose, a JSON tree for structured objects.
         received: valueArray.length === 1 ? valueArray[0] : valueArray,
-        location
+        location,
+        ...unavailable ? { outcome: "error" } : {}
       });
     } catch (error) {
       rec.record(
@@ -1061,7 +1372,8 @@ function createJudgeMethod(rec, judgeConfig, judgeScope) {
           evaluator_type: "llm",
           expected: instruction,
           received: valueArray.length === 1 ? valueArray[0] : valueArray,
-          location
+          location,
+          outcome: "error"
         }
       );
     }
@@ -1085,7 +1397,7 @@ var CAPABILITY_LABELS = {
   skills: "skill",
   subagents: "subagent"
 };
-function createTraceTestContext(view, rec, judgeConfig, judgeScope, agentEvidence) {
+function createTraceTestContext(view, rec, judgeConfig, judgeScope, agentEvidence, judgeTracer) {
   const unsupported = (id, capability) => {
     const label = CAPABILITY_LABELS[capability];
     rec.record(id, false, `${label} evidence is unavailable in this trace projection`, {
@@ -1271,8 +1583,8 @@ function createTraceTestContext(view, rec, judgeConfig, judgeScope, agentEvidenc
     },
     // judge does not consult trace capabilities; the scope carries the
     // task/check frame for prompt builders (#161).
-    judge: createJudgeMethod(rec, judgeConfig, judgeScope),
-    agent: createAgentMethod(rec, judgeConfig, judgeScope, agentEvidence ?? { deliverables: {}, view })
+    judge: trackPending(rec, createJudgeMethod(rec, judgeConfig, judgeScope, judgeTracer)),
+    agent: trackPending(rec, createAgentMethod(rec, judgeConfig, judgeScope, agentEvidence ?? { deliverables: {}, view }, judgeTracer))
   };
 }
 function matchesTraceToolCall(call, name, opts) {
@@ -1293,16 +1605,9 @@ function matchesTraceToolCall(call, name, opts) {
 var Recorder = class {
   constructor(locate) {
     this.records = [];
+    this.pending = [];
     this.locate = locate;
   }
-  /**
-   * Record an assertion.
-   *
-   * - ``extra.location`` overrides auto-capture (used by the runner for thrown
-   *   errors, whose relevant stack is the error's own, not the call site).
-   * - ``extra.expected`` / ``extra.received`` carry the structured values for
-   *   testing-framework-style display.
-   */
   /**
    * Capture the call site location synchronously. Use this when a record will
    * happen AFTER an `await` (e.g. `t.judge`): once an async function resumes,
@@ -1314,6 +1619,28 @@ var Recorder = class {
   captureLocation() {
     return this.locate ? this.locate(new Error().stack ?? "") : void 0;
   }
+  /**
+   * Register an async evaluation (``t.judge`` / ``t.agent``) started by this
+   * check. If the check returns without awaiting it, the runner still waits
+   * for its record via ``settlePending`` — a dropped await must not let the
+   * check vacuously pass ("no assertions recorded") while the verdict is
+   * still in flight.
+   */
+  track(promise) {
+    this.pending.push(promise);
+  }
+  /** Wait until every tracked evaluation has settled (and recorded). */
+  async settlePending() {
+    await Promise.allSettled(this.pending);
+  }
+  /**
+   * Record an assertion.
+   *
+   * - ``extra.location`` overrides auto-capture (used by the runner for thrown
+   *   errors, whose relevant stack is the error's own, not the call site).
+   * - ``extra.expected`` / ``extra.received`` carry the structured values for
+   *   testing-framework-style display.
+   */
   record(id, pass, reasoning, extra) {
     const location = extra?.location ?? (this.locate ? this.locate(new Error().stack ?? "") : void 0);
     this.records.push({
@@ -1425,8 +1752,10 @@ async function runTraceChecks(args) {
         {
           deliverables: args.deliverables,
           view,
-          ...args.historyPlane ? { history: args.historyPlane } : {}
-        }
+          ...args.historyPlane ? { history: args.historyPlane } : {},
+          ...args.historyUnavailableReason ? { historyUnavailable: args.historyUnavailableReason } : {}
+        },
+        args.judgeTracer
       );
       let thrownLocation;
       try {
@@ -1441,8 +1770,10 @@ async function runTraceChecks(args) {
           location: thrownLocation
         });
       }
+      await rec.settlePending();
       const failed = rec.all.filter((r) => !r.pass);
       const pass = failed.length === 0;
+      const outcome = rollUpCheckOutcome(failed);
       const reasoning = failed.length > 0 ? failed.map((r) => r.reasoning || r.id).join("; ") : rec.all.length > 0 ? "passed" : "no assertions recorded";
       const location = failed.find((r) => r.location)?.location;
       const judge = rec.all.find((r) => r.judge)?.judge;
@@ -1451,6 +1782,7 @@ async function runTraceChecks(args) {
         pass,
         reasoning,
         evaluator_type: "code",
+        ...outcome ? { outcome } : {},
         ...judge ? { judge } : {},
         ...location ? { location } : {},
         ...args.displayFile ? { source_file: args.displayFile } : {},
@@ -1465,6 +1797,14 @@ async function runTraceChecks(args) {
   );
   return results;
 }
+function rollUpCheckOutcome(failed) {
+  if (failed.length === 0) return void 0;
+  const verdictless = failed.filter(
+    (r) => r.outcome === "error" || r.outcome === "unsupported"
+  );
+  if (verdictless.length < failed.length) return void 0;
+  return verdictless.some((r) => r.outcome === "error") ? "error" : "unsupported";
+}
 async function loadAndRunFlowChecks(checksPath, args, brokenDeliverables = {}) {
   if (!checksPath) return [];
   resetFlowChecks();
@@ -1477,6 +1817,7 @@ async function loadAndRunFlowChecks(checksPath, args, brokenDeliverables = {}) {
     task: args.task,
     judgeConfig: args.judgeConfig,
     ...args.historyPlane ? { historyPlane: args.historyPlane } : {},
+    ...args.judgeTracer ? { judgeTracer: args.judgeTracer } : {},
     moduleUrl,
     displayFile: basename(checksPath)
   });
@@ -2528,7 +2869,29 @@ function createProjectionTee(real) {
       }
     },
     async traceTool(name, params, fn) {
-      return real.traceTool(name, params, fn);
+      const obsSpanId = recordStart({
+        step_name: `tool ${name}`,
+        observation_type: "TOOL",
+        tool_name: name,
+        input: params
+      });
+      const start = monotonicNowMs();
+      try {
+        const result = await real.traceTool(name, params, fn);
+        complete(obsSpanId, {
+          latency_ms: round3(monotonicNowMs() - start),
+          output: result
+        });
+        return result;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        complete(obsSpanId, {
+          latency_ms: round3(monotonicNowMs() - start),
+          status_message: message,
+          level: "ERROR"
+        });
+        throw error;
+      }
     },
     async traceRetriever(query, fn) {
       return real.traceRetriever(query, fn);
@@ -2719,48 +3082,6 @@ function aggregateResult(checksResults) {
   return { checks: checksResults, pass };
 }
 
-// src/agent-task/tracing.ts
-function createNoopAgentTaskTraceContext() {
-  const noopFn = async (fn) => fn();
-  return {
-    runId: "agent-task-untraced",
-    rootSpanId: "agent-task-untraced-root",
-    async step(options, fn) {
-      return fn(options.id ?? "agent-task-untraced-step");
-    },
-    recordEvent(options) {
-      return options.id ?? "agent-task-untraced-event";
-    },
-    endRoot() {
-    },
-    traceTool(_name, _params, fn) {
-      return noopFn(fn);
-    },
-    traceRetriever(_query, fn) {
-      return noopFn(fn);
-    },
-    traceChain(_name, fn) {
-      return noopFn(fn);
-    },
-    traceAgent(_name, fn) {
-      return noopFn(fn);
-    },
-    traceGuardrail(_name, fn) {
-      return noopFn(fn);
-    },
-    traceEmbedding(_model, _input, fn) {
-      return noopFn(fn);
-    },
-    async score(_params) {
-    },
-    createSpan(_options) {
-      return "agent-task-untraced-span";
-    },
-    endSpan(_spanId, _params) {
-    }
-  };
-}
-
 // src/agent-task/run/runTask.ts
 var AgentTaskRunError = class extends Error {
   constructor(message, options) {
@@ -2787,13 +3108,15 @@ async function runTask(taskDir, options) {
       void 0
     );
   }
-  const phase1 = await trace2.client.traceRun(
+  return trace2.client.traceRun(
     buildTraceRunOptions(loaded, trace2),
-    async (traceContext) => captureExecution(loaded, options, traceContext)
+    async (traceContext) => {
+      const phase1 = await captureExecution(loaded, options, traceContext);
+      const canonical = await readCanonicalSnapshot(trace2);
+      if (canonical) phase1.snapshot = canonical;
+      return evaluate(loaded, options, phase1, traceContext);
+    }
   );
-  const canonical = await readCanonicalSnapshot(trace2);
-  if (canonical) phase1.snapshot = canonical;
-  return evaluate(loaded, options, phase1);
 }
 async function readCanonicalSnapshot(trace2) {
   if (!trace2.taskRunId) return null;
@@ -2991,6 +3314,7 @@ async function executeLoadedTask(loaded, options, rawTrace, traceRunId) {
               files,
               task: task2,
               ...judgeConfig ? { judgeConfig } : {},
+              judgeTracer: trace2,
               ...historyPlane ? { historyPlane } : {}
             },
             validationResults.brokenDeliverables
@@ -3005,6 +3329,7 @@ async function executeLoadedTask(loaded, options, rawTrace, traceRunId) {
           files,
           task: task2,
           ...judgeConfig ? { judgeConfig } : {},
+          judgeTracer: trace2,
           ...historyPlane ? { historyPlane } : {},
           moduleUrl,
           displayFile: evalFileName
@@ -3033,7 +3358,7 @@ async function captureExecution(loaded, options, rawTrace) {
     snapshot: outcome.getSnapshot()
   }));
 }
-async function evaluate(loaded, options, phase1) {
+async function evaluate(loaded, options, phase1, judgeTracer) {
   const {
     task: task2,
     adapter,
@@ -3051,12 +3376,13 @@ async function evaluate(loaded, options, phase1) {
   );
   const judgeConfig = resolveJudgeConfig(options?.judge, task2.judge);
   const historyPlane = await freezeHistoryPlaneFromEnv(task2.id);
-  const checksResults = await (inlineChecks ? runTraceChecks({
+  const runChecks = async () => inlineChecks ? runTraceChecks({
     snapshot: phase1.snapshot,
     deliverables,
     files,
     task: task2,
     ...judgeConfig ? { judgeConfig } : {},
+    ...judgeTracer ? { judgeTracer } : {},
     ...historyPlane ? { historyPlane } : {},
     moduleUrl,
     displayFile: evalFileName
@@ -3068,10 +3394,22 @@ async function evaluate(loaded, options, phase1) {
       files,
       task: task2,
       ...judgeConfig ? { judgeConfig } : {},
+      ...judgeTracer ? { judgeTracer } : {},
       ...historyPlane ? { historyPlane } : {}
     },
     validationResults.brokenDeliverables
-  ));
+  );
+  const hasChecksModule = inlineChecks || checksPath !== null;
+  const checksResults = await (judgeTracer && hasChecksModule ? judgeTracer.step(
+    {
+      step_name: "checks.run",
+      observation_type: "CHAIN",
+      input: { sourceFile: inlineChecks ? evalFileName : checksPath },
+      metadata: { sourceFile: inlineChecks ? evalFileName : checksPath },
+      summarize: (result2) => summarizeEvaluationResults(result2)
+    },
+    runChecks
+  ) : runChecks());
   const result = aggregateResult(checksResults);
   return {
     task: task2,
@@ -3169,17 +3507,29 @@ async function cleanupAdapter(loaded, trace2, state, session) {
 }
 function summarizeEvaluationResults(results) {
   const passCount = results.filter((r) => r.pass).length;
+  const noVerdictCount = results.filter(
+    (r) => !r.pass && (r.outcome === "error" || r.outcome === "unsupported")
+  ).length;
+  const failCount = results.length - passCount - noVerdictCount;
+  const suffix = noVerdictCount > 0 ? ` (${noVerdictCount} no-verdict)` : "";
   return {
-    total: results.length,
-    passCount,
-    failCount: results.length - passCount,
-    results: results.map((r) => ({
-      id: r.id,
-      pass: r.pass,
-      reasoning: r.reasoning,
-      evaluator_type: r.evaluator_type,
-      judge_model: r.judge?.model
-    }))
+    text: `${passCount}/${results.length} checks passed${suffix}`,
+    verdict: {
+      total: results.length,
+      passCount,
+      failCount,
+      noVerdictCount,
+      results: results.map((r) => ({
+        id: r.id,
+        pass: r.pass,
+        reasoning: r.reasoning?.slice(0, 2e3),
+        evaluator_type: r.evaluator_type,
+        judge_model: r.judge?.model,
+        ...r.outcome ? { outcome: r.outcome } : {},
+        ...r.group_id ? { group_id: r.group_id } : {},
+        ...r.group_name ? { group_name: r.group_name } : {}
+      }))
+    }
   };
 }
 function buildTraceRunOptions(loaded, tracing) {
@@ -3307,6 +3657,7 @@ async function rejudgeTaskRun(runId, endpoints, options = {}) {
     );
     const proxied = proxyBrokenDeliverables(deliverables, validation.brokenDeliverables);
     const passCounts = /* @__PURE__ */ new Map();
+    const errorCounts = /* @__PURE__ */ new Map();
     let primary = [];
     const judgeConfig = resolveJudgeConfig(options.judge, loaded.task.judge);
     for (let sample = 0; sample < samples; sample++) {
@@ -3315,12 +3666,16 @@ async function rejudgeTaskRun(runId, endpoints, options = {}) {
       if (sample === 0) primary = results;
       for (const result of results) {
         passCounts.set(result.id, (passCounts.get(result.id) ?? 0) + (result.pass ? 1 : 0));
+        if (!result.pass && result.outcome === "error") {
+          errorCounts.set(result.id, (errorCounts.get(result.id) ?? 0) + 1);
+        }
       }
     }
     const stability = primary.map((result) => ({
       check_id: result.id,
       passes: passCounts.get(result.id) ?? 0,
-      samples
+      samples,
+      ...errorCounts.get(result.id) ? { errored: errorCounts.get(result.id) } : {}
     }));
     const aggregate = aggregateResult(primary);
     return {
@@ -3544,6 +3899,7 @@ function createOtelAgentTaskTraceClient(config) {
     activeSpans.set(spanId, {
       span,
       startedAt: monotonicNowMs2(),
+      startWallMs: Date.now(),
       model: params.model || "unknown",
       observationType: params.observation_type
     });
@@ -3561,6 +3917,13 @@ function createOtelAgentTaskTraceClient(config) {
         const payload = params.output && typeof params.output === "object" ? params.output : { value: params.output };
         active.span.setAttribute("gen_ai.tool.call.result", JSON.stringify(payload));
       } else if (params.output.text) {
+        active.span.setAttribute("gen_ai.response.text", String(params.output.text));
+        if (params.output.verdict !== void 0) {
+          active.span.setAttribute(
+            "gen_ai.tool.call.result",
+            JSON.stringify(params.output.verdict)
+          );
+        }
         active.span.setAttribute("gen_ai.output.messages", JSON.stringify([{
           role: "assistant",
           parts: [{ type: "text", content: String(params.output.text) }]
@@ -3585,6 +3948,12 @@ function createOtelAgentTaskTraceClient(config) {
     if (params.completion_tokens !== void 0) {
       active.span.setAttribute("gen_ai.usage.output_tokens", params.completion_tokens);
     }
+    if (params.reasoning_tokens !== void 0) {
+      active.span.setAttribute(
+        "gen_ai.usage.reasoning.output_tokens",
+        params.reasoning_tokens
+      );
+    }
     if (params.status_message) {
       active.span.setAttribute("apo.status_message", params.status_message);
     }
@@ -3594,7 +3963,7 @@ function createOtelAgentTaskTraceClient(config) {
     if (params.metadata) {
       active.span.setAttribute("apo.metadata", JSON.stringify(params.metadata));
     }
-    active.span.end();
+    active.span.end(new Date(active.startWallMs + latency));
     activeSpans.delete(params.id);
   }
   return {
@@ -3628,6 +3997,7 @@ function createOtelAgentTaskTraceClient(config) {
       activeSpans.set(rootSpanId, {
         span: rootSpan,
         startedAt: monotonicNowMs2(),
+        startWallMs: Date.now(),
         model: "trace"
       });
       let callCount = 1;
@@ -3653,7 +4023,8 @@ function createOtelAgentTaskTraceClient(config) {
               id: spanId,
               latency_ms: round32(monotonicNowMs2() - startedAt),
               output: options.summarize?.(result),
-              metadata: options.metadata
+              metadata: options.metadata,
+              ...options.usage?.(result)
             });
             callCount += 1;
             return result;