@apo-ai/sdk 0.16.1 → 0.17.0

package/dist/agent-task/public.js

@@ -9,20 +9,70 @@ import {
   resolveApoAuthHeaders,
   withApoRun,
   withApoRunSync
-} from "../chunk-YWUTUQPJ.js";
+} from "../chunk-CSOY6OSP.js";
 import {
   createApoTracer
 } from "../chunk-OZWOLCJ5.js";
 import "../chunk-HRYXLRXJ.js";
 import {
   createApoOpenAI
-} from "../chunk-NSMKSPBU.js";
+} from "../chunk-Z7DVZ34X.js";
 import {
   createApoAnthropic
-} from "../chunk-4BQSCD6T.js";
+} from "../chunk-6U6V7VKZ.js";
 import {
   servingHostFromBaseURL
-} from "../chunk-JN7RHBTS.js";
+} from "../chunk-KWIYQSWK.js";
+
+// src/agent-task/trace-projection/retrieval.ts
+function parseRetrievedDocuments(output) {
+  const array = documentsArray(output);
+  if (array === void 0) return void 0;
+  const documents = [];
+  for (const item of array) {
+    const document = parseDocument(item);
+    if (document !== void 0) documents.push(document);
+  }
+  return documents;
+}
+function documentsFromObservation(obs) {
+  return parseRetrievedDocuments(obs.toolResult) ?? parseRetrievedDocuments(obs.output);
+}
+function retrievalQueryFrom(obs) {
+  return queryIn(obs.toolParameters) ?? queryIn(obs.input);
+}
+function queryIn(value) {
+  if (value != null && typeof value === "object") {
+    const query = value.query;
+    if (typeof query === "string") return query;
+  }
+  return void 0;
+}
+function documentsArray(output) {
+  if (Array.isArray(output)) return output;
+  if (output != null && typeof output === "object") {
+    const wrapped = output.documents;
+    if (Array.isArray(wrapped)) return wrapped;
+  }
+  return void 0;
+}
+function parseDocument(item) {
+  if (typeof item === "string") {
+    return item.length > 0 ? { content: item } : void 0;
+  }
+  if (item == null || typeof item !== "object") return void 0;
+  const record = item;
+  const rawContent = record.content ?? record.text;
+  const content = typeof rawContent === "string" ? rawContent : "";
+  const id = typeof record.id === "string" && record.id.length > 0 ? record.id : void 0;
+  if (content.length === 0 && id === void 0) return void 0;
+  const document = { content };
+  if (id !== void 0) document.id = id;
+  if (typeof record.score === "number" && Number.isFinite(record.score)) {
+    document.score = record.score;
+  }
+  return document;
+}
 
 // src/agent-task/run/steer-scheduler.ts
 var TASK_STEER_SPAN_NAME = "task.steer";
@@ -277,6 +327,18 @@ var TraceView = class _TraceView {
   get toolNamesInOrder() {
     return this.toolCalls.map((c) => c.name);
   }
+  /** Retrievals derived from `RETRIEVER` observations, in invocation order. */
+  get retrievals() {
+    return this.sortedObservations.filter((o) => o.type === "RETRIEVER").map((o) => {
+      const retrieval = { spanId: o.spanId, status: o.status };
+      const query = retrievalQueryFrom(o);
+      if (query !== void 0) retrieval.query = query;
+      const documents = documentsFromObservation(o);
+      if (documents !== void 0) retrieval.documents = documents;
+      if (o.startedAt !== void 0) retrieval.startedAt = o.startedAt;
+      return retrieval;
+    });
+  }
   /** Skill loads derived from `SKILL` observations, in invocation order. */
   get skillLoads() {
     return this.sortedObservations.filter((o) => o.type === "SKILL").map((o) => ({ spanId: o.spanId, skill: o.name, startedAt: o.startedAt }));
@@ -2860,7 +2922,7 @@ function createAgentMethod(rec, judgeConfig, judgeScope, evidence, judgeTracer,
       rec.record(
         label,
         false,
-        "No judge model configured for t.agent. Set one of:\n\u2022 OPENROUTER_MODEL + OPENROUTER_API_KEY (OpenRouter \u2014 needs a tool-calling-capable model)\n\u2022 OPENAI_MODEL + OPENAI_API_KEY (OpenAI direct)\n\u2022 ANTHROPIC_MODEL + ANTHROPIC_API_KEY (Anthropic direct \u2014 needs a tool-calling-capable model; or ANTHROPIC_AUTH_TOKEN for plan credits)\nOr pass { judge } to runTask() programmatically.",
+        "No judge model configured for t.agent. Set one of:\n\u2022 AGENT_TASK_OPENROUTER_MODEL or OPENROUTER_MODEL + OPENROUTER_API_KEY (OpenRouter, needs a tool-calling-capable model)\n\u2022 OPENAI_MODEL + OPENAI_API_KEY (OpenAI direct)\n\u2022 ANTHROPIC_MODEL + ANTHROPIC_API_KEY (Anthropic direct, needs a tool-calling-capable model, or ANTHROPIC_AUTH_TOKEN for plan credits)\nOr pass { judge } to runTask() programmatically.",
         { evaluator_type: "agent", location, outcome: "error" }
       );
       return;
@@ -2961,6 +3023,246 @@ function createAgentMethod(rec, judgeConfig, judgeScope, evidence, judgeTracer,
   };
 }
 
+// src/agent-task/checks/grounded.ts
+var GROUNDEDNESS_RUBRIC = [
+  "Value 1 is an answer. Value 2 is the set of source documents the answer was supposed to rely on.",
+  "Decide whether the answer is grounded in the sources. Check every factual claim in the answer. A claim is supported only when a source states it, or it follows directly from what a source states. Greetings, hedges, and statements that the answer cannot help are not factual claims.",
+  "PASS when every factual claim is supported. FAIL when any factual claim is unsupported or contradicted by the sources, even if it is true in the real world. Groundedness measures the answer against these sources, not against your own knowledge. In your reasoning, name each unsupported claim."
+].join("\n\n");
+function formatTraceSources(retrievals) {
+  const seen = /* @__PURE__ */ new Set();
+  const documents = [];
+  for (const retrieval of retrievals) {
+    for (const document of retrieval.documents ?? []) {
+      const key = document.id ?? document.content;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      documents.push(document);
+    }
+  }
+  return formatSources(documents);
+}
+function formatAuthorSources(sources) {
+  return formatSources(sources.map((content) => ({ content })));
+}
+function formatSources(documents) {
+  if (documents.length === 0) return "(no documents were retrieved)";
+  return documents.map((document, i) => {
+    const heading = document.id === void 0 ? `[${i + 1}]` : `[${i + 1}] ${document.id}`;
+    return `${heading}
+${document.content}`;
+  }).join("\n\n");
+}
+
+// src/agent-task/checks/embedding.ts
+function isEmbeddingHttpConfig(provider) {
+  return typeof provider.model === "string";
+}
+function resolveEmbeddingConfig(provider, override) {
+  const base = resolveEmbeddingProvider(provider);
+  if (!override) return base;
+  if (base?.custom && !override.model) return base;
+  const baseConfig = base?.config;
+  if (!override.model && !baseConfig) return void 0;
+  return {
+    config: {
+      model: override.model ?? baseConfig.model,
+      baseURL: override.baseURL ?? baseConfig?.baseURL,
+      apiKey: override.apiKey ?? baseConfig?.apiKey,
+      dimensions: override.dimensions ?? baseConfig?.dimensions
+    }
+  };
+}
+function resolveEmbeddingProvider(provider) {
+  if (!provider) return void 0;
+  if ("config" in provider || "custom" in provider) return provider;
+  return isEmbeddingHttpConfig(provider) ? { config: provider } : { custom: provider };
+}
+var EmbeddingUnavailableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EmbeddingUnavailableError";
+  }
+};
+function createEmbeddingClient() {
+  const resolved = /* @__PURE__ */ new Map();
+  const inflight = /* @__PURE__ */ new Map();
+  return {
+    async embed(texts, provider) {
+      const inputs = texts.map((text) => text.replace(/\r?\n/g, " "));
+      const keyed = inputs.map((text) => ({ text, key: cacheKeyFor(text, provider) }));
+      const seen = /* @__PURE__ */ new Set();
+      const needFetch = keyed.filter(({ key }) => {
+        if (resolved.has(key) || inflight.has(key) || seen.has(key)) return false;
+        seen.add(key);
+        return true;
+      });
+      let fetchedMeta;
+      if (needFetch.length > 0) {
+        const fetchPromise = (async () => fetchEmbeddings(needFetch.map((n) => n.text), provider))();
+        for (let i = 0; i < needFetch.length; i++) {
+          const promise = fetchPromise.then((fetched) => {
+            fetchedMeta = {
+              dimensions: fetched.dimensions,
+              ...fetched.servedModel !== void 0 ? { servedModel: fetched.servedModel } : {},
+              ...fetched.tokens !== void 0 ? { tokens: fetched.tokens } : {},
+              ...fetched.latencyMs !== void 0 ? { latencyMs: fetched.latencyMs } : {}
+            };
+            return fetched.vectors[i];
+          });
+          inflight.set(needFetch[i].key, promise);
+        }
+        void Promise.allSettled(needFetch.map(({ key }) => inflight.get(key))).then(() => {
+          for (const { key } of needFetch) inflight.delete(key);
+        });
+      }
+      const vectors = await Promise.all(
+        keyed.map(async ({ key }) => {
+          const inFlight = inflight.get(key);
+          if (inFlight !== void 0) {
+            const vector = await inFlight;
+            resolved.set(key, vector);
+            return vector;
+          }
+          const cached = resolved.get(key);
+          if (cached !== void 0) return cached;
+          throw new EmbeddingUnavailableError("embedding vector vanished: concurrent cache race");
+        })
+      );
+      const dims = vectors[0].length;
+      if (vectors.some((v) => v.length !== dims)) {
+        throw new EmbeddingUnavailableError("provider returned vectors of mixed dimensionality");
+      }
+      return {
+        vectors,
+        dimensions: dims,
+        ...fetchedMeta?.servedModel !== void 0 ? { servedModel: fetchedMeta.servedModel } : {},
+        ...fetchedMeta?.tokens !== void 0 ? { tokens: fetchedMeta.tokens } : {},
+        ...fetchedMeta?.latencyMs !== void 0 ? { latencyMs: fetchedMeta.latencyMs } : {}
+      };
+    }
+  };
+}
+function cacheKeyFor(text, provider) {
+  if (provider.custom) return `custom|${text}`;
+  const c = provider.config;
+  return `${c.model}|${c.baseURL ?? ""}|${c.dimensions ?? "auto"}|${text}`;
+}
+async function fetchEmbeddings(inputs, provider) {
+  const startedAt = Date.now();
+  if (provider.custom) {
+    const vectors = await provider.custom.embed(inputs);
+    if (!Array.isArray(vectors) || vectors.length !== inputs.length) {
+      throw new EmbeddingUnavailableError(
+        `custom embed function returned ${vectors?.length ?? 0} vectors for ${inputs.length} inputs`
+      );
+    }
+    return { vectors, dimensions: vectors[0]?.length ?? 0, latencyMs: Date.now() - startedAt };
+  }
+  const config = provider.config;
+  const call = (omitDimensions) => requestEmbeddings(config, inputs, omitDimensions);
+  const first = await callWithRetry(() => call(false));
+  const result = first.kind === "rejected-dimensions" ? await callWithRetry(() => call(true)) : first;
+  if (result.kind !== "ok") throw new Error(result.message);
+  return {
+    vectors: result.vectors,
+    ...result.servedModel ? { servedModel: result.servedModel } : {},
+    dimensions: result.vectors[0]?.length ?? 0,
+    ...result.tokens ? { tokens: result.tokens } : {},
+    latencyMs: Date.now() - startedAt
+  };
+}
+async function callWithRetry(call) {
+  const first = await call();
+  if (first.kind !== "error" || first.status !== 429) return first;
+  const retryAfter = Number(first.message.match(/retry-after (\d+)/)?.[1] ?? 1);
+  await new Promise((resolve5) => setTimeout(resolve5, Math.min(retryAfter, 10) * 1e3));
+  return call();
+}
+async function requestEmbeddings(config, inputs, omitDimensions) {
+  if (!config.baseURL) {
+    return {
+      kind: "error",
+      message: "no embeddings endpoint configured: set APO_EMBEDDING_BASE_URL (or pass baseURL), e.g. https://openrouter.ai/api/v1 or a local server like http://localhost:11434/v1"
+    };
+  }
+  const url = `${config.baseURL.replace(/\/$/, "")}/embeddings`;
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...config.apiKey ? { authorization: `Bearer ${config.apiKey}` } : {}
+      },
+      body: JSON.stringify({
+        model: config.model,
+        input: inputs,
+        ...omitDimensions ? {} : config.dimensions !== void 0 ? { dimensions: config.dimensions } : {}
+      })
+    });
+  } catch (error) {
+    return { kind: "error", message: `embeddings endpoint unreachable: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  if (response.status === 400) {
+    const body2 = await response.text();
+    if (/dimensions/i.test(body2)) return { kind: "rejected-dimensions", message: body2 };
+    return { kind: "error", status: 400, message: `embeddings request rejected (400): ${body2}` };
+  }
+  if (response.status === 429) {
+    const retryAfter = response.headers.get("retry-after");
+    return { kind: "error", status: 429, message: `embeddings rate-limited (429), retry-after ${retryAfter ?? 1}` };
+  }
+  if (!response.ok) {
+    const body2 = await response.text();
+    return { kind: "error", status: response.status, message: `embeddings request failed (${response.status}): ${body2.slice(0, 500)}` };
+  }
+  const body = await response.json();
+  const data = body.data;
+  if (!Array.isArray(data) || data.length !== inputs.length) {
+    return { kind: "error", message: `embeddings response malformed: expected ${inputs.length} vectors, got ${data?.length ?? "none"}` };
+  }
+  const vectors = Array.from({ length: data.length });
+  data.forEach((item, position) => {
+    const vector = item.embedding;
+    if (!Array.isArray(vector) || vector.some((v) => typeof v !== "number")) {
+      throw new EmbeddingUnavailableError("embeddings response malformed: a returned embedding is not a number array");
+    }
+    const slot = typeof item.index === "number" && item.index >= 0 && item.index < data.length ? item.index : position;
+    vectors[slot] = vector;
+  });
+  if (vectors.some((v) => v === void 0)) {
+    return { kind: "error", message: "embeddings response malformed: index field named a slot outside the response" };
+  }
+  return {
+    kind: "ok",
+    vectors,
+    ...typeof body.model === "string" ? { servedModel: body.model } : {},
+    ...typeof body.usage?.prompt_tokens === "number" ? { tokens: { input: body.usage.prompt_tokens } } : {}
+  };
+}
+function cosineSimilarity(a, b) {
+  if (a.length !== b.length) return Number.NaN;
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  if (normA === 0 || normB === 0) return 0;
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+function vectorMagnitude(v) {
+  let sum = 0;
+  for (const x of v) sum += x * x;
+  return Math.sqrt(sum);
+}
+function embeddingSettingsSignature(model, dimensions) {
+  return `${model}:${dimensions}d:cosine:apo-v1`;
+}
+
 // src/agent-task/checks/t.ts
 function resolveJudgeConfig(judgeConfig, override) {
   const model = override?.model ?? judgeConfig?.model;
@@ -2982,6 +3284,8 @@ var TEST_METHOD_NAMES = [
   "usedNoTools",
   "maxToolCalls",
   "noFailedActions",
+  "retrieved",
+  "maxRetrievals",
   "loadedSkill",
   "calledSubagent",
   "messageIncludes",
@@ -2992,9 +3296,12 @@ var TEST_METHOD_NAMES = [
   "steerDelivered",
   "afterSteer",
   "assert",
+  "not",
   "check",
   "judge",
-  "agent"
+  "semantic",
+  "agent",
+  "grounded"
 ];
 function describeName(m) {
   if (typeof m === "string") return `"${m}"`;
@@ -3075,7 +3382,7 @@ function createJudgeMethod(rec, judgeConfig, judgeScope, judgeTracer) {
       rec.record(
         label,
         false,
-        "No judge model configured. Set one of:\n\u2022 OPENROUTER_MODEL + OPENROUTER_API_KEY (OpenRouter \u2014 works with 200+ models, one account)\n\u2022 OPENAI_MODEL + OPENAI_API_KEY (OpenAI direct)\n\u2022 ANTHROPIC_MODEL + ANTHROPIC_API_KEY (Anthropic direct \u2014 or ANTHROPIC_AUTH_TOKEN for plan credits)\nOr pass { judge } to runTask() programmatically.",
+        "No judge model configured. Set one of:\n\u2022 AGENT_TASK_OPENROUTER_MODEL or OPENROUTER_MODEL + OPENROUTER_API_KEY (OpenRouter, 200+ models, one account)\n\u2022 OPENAI_MODEL + OPENAI_API_KEY (OpenAI direct)\n\u2022 ANTHROPIC_MODEL + ANTHROPIC_API_KEY (Anthropic direct, or ANTHROPIC_AUTH_TOKEN for plan credits)\nOr pass { judge } to runTask() programmatically.",
         // No judge means no verdict — the same bucket as an unreachable judge.
         { evaluator_type: "llm", location, outcome: "error" }
       );
@@ -3184,7 +3491,10 @@ function createJudgeMethod(rec, judgeConfig, judgeScope, judgeTracer) {
             text: res?.reasoning?.slice(0, 2e3) ?? "",
             verdict: {
               reasoning: res?.reasoning?.slice(0, 2e3) ?? null,
-              pass: res?.pass ?? null
+              pass: res?.pass ?? null,
+              // A judge that gave no verdict still reports pass: false;
+              // the outcome tells a trace reader it is not a "no".
+              ...res?.unavailable ? { outcome: "error" } : {}
             }
           };
         },
@@ -3255,6 +3565,143 @@ function judgeScopeToContext(scope) {
     ...deliverableNames && deliverableNames.length > 0 ? { deliverableNames } : {}
   };
 }
+function createSemanticMethod(rec, embedding, judgeScope) {
+  const client = embedding?.client ?? createEmbeddingClient();
+  const previewOf = (text) => text.length > 120 ? `${text.slice(0, 117)}...` : text;
+  return async (value, reference, opts) => {
+    const label = opts?.label ?? "semantic";
+    const location = rec.captureLocation();
+    const threshold = opts.threshold;
+    if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
+      rec.record(
+        label,
+        false,
+        `t.semantic: threshold must be a finite number in [0, 1], got ${threshold}`,
+        { evaluator_type: "embedding", location }
+      );
+      return;
+    }
+    const resolved = resolveEmbeddingConfig(embedding?.provider, opts.embedding);
+    if (!resolved) {
+      rec.record(
+        label,
+        false,
+        "No embedding model configured. Set one of:\n\u2022 APO_EMBEDDING_MODEL + APO_EMBEDDING_API_KEY (+ APO_EMBEDDING_BASE_URL for a local server)\n\u2022 OPENROUTER_API_KEY (defaults to openai/text-embedding-3-small via OpenRouter)\n\u2022 OPENAI_API_KEY (defaults to text-embedding-3-small)\nOr pass { embedding } to runTask() programmatically.",
+        { evaluator_type: "embedding", location, outcome: "error" }
+      );
+      return;
+    }
+    const valueText = typeof value === "string" ? value : describeValue(value);
+    const modelName = resolved.config?.model ?? "custom";
+    const tracer = embedding?.tracer;
+    const grade = (result) => {
+      const [valueVector, referenceVector] = result.vectors;
+      const similarity2 = cosineSimilarity(valueVector, referenceVector);
+      if (!Number.isFinite(similarity2)) {
+        throw new Error("cosine similarity undefined: provider returned non-finite vector components");
+      }
+      const rounded = Math.round(similarity2 * 1e4) / 1e4;
+      return {
+        similarity: rounded,
+        pass: rounded >= threshold,
+        signature: embeddingSettingsSignature(modelName, result.dimensions),
+        dimensions: result.dimensions,
+        ...result.servedModel ? { servedModel: result.servedModel } : {},
+        ...result.tokens ? { tokens: result.tokens } : {},
+        ...result.latencyMs !== void 0 ? { latencyMs: result.latencyMs } : {},
+        zeroMagnitude: vectorMagnitude(valueVector) === 0 || vectorMagnitude(referenceVector) === 0
+      };
+    };
+    let spanId;
+    const call = () => client.embed([valueText, reference], resolved);
+    try {
+      const verdict = await (tracer ? tracer.step(
+        {
+          step_name: `embedding:${judgeScope?.checkName ?? label}`,
+          observation_type: "EMBEDDING",
+          model: modelName,
+          ...servingHostFromBaseURL(resolved.config?.baseURL),
+          input: { model: modelName, threshold },
+          summarize: (r) => {
+            const res = r;
+            const text = `cosine ${res.similarity} vs threshold ${threshold}` + (res.pass ? ": pass" : ": fail");
+            return {
+              text,
+              verdict: {
+                pass: res.pass,
+                similarity: res.similarity,
+                threshold,
+                settings: res.signature
+              }
+            };
+          },
+          usage: (r) => {
+            const tokens = r.tokens;
+            return tokens?.input !== void 0 ? { prompt_tokens: tokens.input } : void 0;
+          }
+        },
+        async (id) => {
+          spanId = id;
+          return grade(await call());
+        }
+      ) : grade(await call()));
+      const delta = verdict.similarity - threshold;
+      let reasoning = verdict.pass ? `semantic similarity ${verdict.similarity.toFixed(4)} \u2265 ${threshold.toFixed(4)} [${verdict.signature}]` : `semantic similarity ${verdict.similarity.toFixed(4)} < ${threshold.toFixed(4)} (delta ${delta.toFixed(4)}) [${verdict.signature}]`;
+      if (Math.abs(delta) < 0.02) {
+        reasoning += ". Verdict is marginal: within 0.02 of the threshold, it will flip on model drift";
+      }
+      if (verdict.zeroMagnitude) {
+        reasoning += " (zero-magnitude vector: the provider returned an empty direction)";
+      }
+      const metadata = {
+        model: modelName,
+        ...verdict.servedModel ? { served_model: verdict.servedModel } : {},
+        dimensions: verdict.dimensions,
+        similarity: verdict.similarity,
+        threshold,
+        metric: "cosine",
+        settings_hash: verdict.signature,
+        ...verdict.tokens ? { tokens: verdict.tokens } : {},
+        ...verdict.latencyMs !== void 0 ? { latency_ms: verdict.latencyMs } : {},
+        ...isTraceableSpanId(spanId) ? { span_id: spanId } : {},
+        value_preview: previewOf(valueText),
+        reference_preview: previewOf(reference)
+      };
+      rec.record(label, verdict.pass, reasoning, {
+        evaluator_type: "embedding",
+        expected: `cosine \u2265 ${threshold.toFixed(4)} (${modelName}:${verdict.dimensions}d)`,
+        received: verdict.similarity,
+        location,
+        embedding: metadata
+      });
+      if (tracer && isTraceableSpanId(spanId)) {
+        try {
+          await tracer.score({
+            name: "semantic_similarity",
+            value: verdict.similarity,
+            dataType: "NUMERIC",
+            source: "EVAL",
+            observationId: spanId
+          }).catch(() => void 0);
+        } catch {
+        }
+      }
+    } catch (error) {
+      rec.record(
+        label,
+        false,
+        `embedding check failed: ${error instanceof Error ? error.message : String(error)}`,
+        {
+          evaluator_type: "embedding",
+          expected: `cosine \u2265 ${threshold.toFixed(4)}`,
+          received: valueText,
+          location,
+          outcome: "error"
+        }
+      );
+    }
+  };
+}
 var CAPABILITY_LABELS = {
   messages: "message",
   tools: "tool",
@@ -3262,9 +3709,10 @@ var CAPABILITY_LABELS = {
   timing: "timing",
   skills: "skill",
   subagents: "subagent",
-  usage: "token usage"
+  usage: "token usage",
+  retrieval: "retrieval"
 };
-function createTraceTestContext(view, rec, judgeConfig, judgeScope, agentEvidence, judgeTracer, judgeTools) {
+function createTraceTestContext(view, rec, judgeConfig, judgeScope, agentEvidence, judgeTracer, judgeTools, embedding) {
   const unsupported = (id, capability) => {
     const label = CAPABILITY_LABELS[capability];
     rec.record(id, false, `${label} evidence is unavailable in this trace projection`, {
@@ -3274,7 +3722,24 @@ function createTraceTestContext(view, rec, judgeConfig, judgeScope, agentEvidenc
     });
   };
   const isAvailable = (c) => view.requireCapability(c) === "available";
-  return {
+  const traceSourcesFor = (label) => {
+    if (!isAvailable("retrieval")) {
+      unsupported(label, "retrieval");
+      return void 0;
+    }
+    const opaque = view.retrievals.filter((r) => r.documents === void 0).length;
+    if (opaque > 0) {
+      rec.record(label, false, `${opaque} retrieval(s) returned results in an unrecognized shape, so the sources are incomplete`, {
+        evaluator_type: "llm",
+        outcome: "unsupported",
+        expected: "every retrieval's documents known",
+        received: `${opaque} unrecognized retrieval result(s)`
+      });
+      return void 0;
+    }
+    return formatTraceSources(view.retrievals);
+  };
+  const context2 = {
     calledTool(name, opts) {
       if (!isAvailable("tools")) {
         unsupported(`calledTool(${describeName(name)})`, "tools");
@@ -3372,6 +3837,51 @@ function createTraceTestContext(view, rec, judgeConfig, judgeScope, agentEvidenc
         received: `${failed}`
       });
     },
+    retrieved(document, opts) {
+      requireTopK(opts?.topK);
+      const id = `retrieved(${describeDocument(document)}${describeRetrievedOptions(opts)})`;
+      if (!isAvailable("retrieval")) {
+        unsupported(id, "retrieval");
+        return;
+      }
+      const expected = `${describeDocument(document)} retrieved${describeRetrievedOptions(opts)}`;
+      const scoped = view.retrievals.filter(
+        (r) => opts?.query === void 0 || (r.query?.includes(opts.query) ?? false)
+      );
+      const hit = findRetrievedDocument(scoped, document, opts?.topK);
+      if (hit !== void 0) {
+        rec.record(id, true, "", { expected, received: hit });
+        return;
+      }
+      const opaque = scoped.filter((r) => r.documents === void 0).length;
+      if (opaque > 0) {
+        rec.record(
+          id,
+          false,
+          `${opaque} retrieval(s) in scope returned results in an unrecognized shape`,
+          { outcome: "unsupported", expected, received: `${opaque} unrecognized retrieval result(s)` }
+        );
+        return;
+      }
+      rec.record(
+        id,
+        false,
+        scoped.length === 0 ? `no retrieval ran with a query containing "${opts?.query ?? ""}"` : `no retrieval returned ${describeDocument(document)}${describeRetrievedOptions(opts)}`,
+        { expected, received: summarizeRetrievals(scoped) }
+      );
+    },
+    maxRetrievals(n) {
+      requireBudget("maxRetrievals", n);
+      if (view.requireCapability("retrieval") === "unavailable") {
+        unsupported(`maxRetrievals(${n})`, "retrieval");
+        return;
+      }
+      const count = view.retrievals.length;
+      rec.record(`maxRetrievals(${n})`, count <= n, count <= n ? "" : `expected \u2264 ${n} retrievals, got ${count}`, {
+        expected: `\u2264 ${n} retrievals`,
+        received: `${count}`
+      });
+    },
     loadedSkill(skill) {
       if (!isAvailable("skills")) {
         unsupported(`loadedSkill("${skill}")`, "skills");
@@ -3459,7 +3969,8 @@ function createTraceTestContext(view, rec, judgeConfig, judgeScope, agentEvidenc
         judgeScope,
         agentEvidence,
         judgeTracer,
-        judgeTools
+        judgeTools,
+        embedding
       )
     ),
     check(value, matcher, label) {
@@ -3474,7 +3985,38 @@ 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: trackPending(rec, createJudgeMethod(rec, judgeConfig, judgeScope, judgeTracer)),
-    agent: trackPending(rec, createAgentMethod(rec, judgeConfig, judgeScope, agentEvidence ?? { deliverables: {}, view }, judgeTracer, judgeTools))
+    agent: trackPending(rec, createAgentMethod(rec, judgeConfig, judgeScope, agentEvidence ?? { deliverables: {}, view }, judgeTracer, judgeTools)),
+    // Like t.judge: value-plane check, no capability gating — but traced, so
+    // the embeddings call shows up as an EMBEDDING observation.
+    semantic: trackPending(rec, createSemanticMethod(rec, embedding, judgeScope)),
+    async grounded(value, opts) {
+      const label = opts?.label ?? "grounded";
+      const sources = opts?.sources ?? "trace";
+      const sourceList = sources === "trace" ? traceSourcesFor(label) : formatAuthorSources(sources);
+      if (sourceList === void 0) return;
+      await context2.judge([value, sourceList], GROUNDEDNESS_RUBRIC, {
+        label,
+        judge: opts?.judge,
+        expect: opts?.expect
+      });
+    },
+    get not() {
+      return createNotContext(context2, rec);
+    }
+  };
+  return context2;
+}
+function createNotContext(t, rec) {
+  return {
+    calledTool: (name, opts) => rec.negated(() => t.calledTool(name, opts)),
+    toolOrder: (names) => rec.negated(() => t.toolOrder(names)),
+    loadedSkill: (skill) => rec.negated(() => t.loadedSkill(skill)),
+    calledSubagent: (agent) => rec.negated(() => t.calledSubagent(agent)),
+    messageIncludes: (token) => rec.negated(() => t.messageIncludes(token)),
+    retrieved: (document, opts) => rec.negated(() => t.retrieved(document, opts)),
+    check(value, matcher, label) {
+      rec.negated(() => t.check(value, matcher, label));
+    }
   };
 }
 function requireBudget(method, n) {
@@ -3579,14 +4121,76 @@ function matchesTraceToolCall(call, name, opts) {
   }
   return true;
 }
+function findRetrievedDocument(retrievals, document, topK) {
+  for (const retrieval of retrievals) {
+    const documents = retrieval.documents ?? [];
+    const limit = topK === void 0 ? documents.length : Math.min(topK, documents.length);
+    for (let i = 0; i < limit; i++) {
+      if (matchesDocument(documents[i], document)) {
+        return `rank ${i + 1} for query "${retrieval.query ?? "(none recorded)"}"`;
+      }
+    }
+  }
+  return void 0;
+}
+function matchesDocument(doc, matcher) {
+  if (typeof matcher === "string") {
+    return doc.id === matcher || (doc.id?.startsWith(`${matcher}#`) ?? false);
+  }
+  if ("id" in matcher) return doc.id === matcher.id;
+  if ("idPrefix" in matcher) return doc.id?.startsWith(matcher.idPrefix) ?? false;
+  return doc.content.includes(matcher.contentIncludes);
+}
+function describeDocument(matcher) {
+  if (typeof matcher === "string") return `"${matcher}"`;
+  if ("id" in matcher) return `{ id: "${matcher.id}" }`;
+  if ("idPrefix" in matcher) return `{ idPrefix: "${matcher.idPrefix}" }`;
+  return `{ contentIncludes: "${matcher.contentIncludes}" }`;
+}
+function describeRetrievedOptions(opts) {
+  const parts = [];
+  if (opts?.topK !== void 0) parts.push(`in top ${opts.topK}`);
+  if (opts?.query !== void 0) parts.push(`for query containing "${opts.query}"`);
+  return parts.length > 0 ? ` ${parts.join(" ")}` : "";
+}
+function summarizeRetrievals(retrievals) {
+  if (retrievals.length === 0) return "(no retrievals)";
+  return retrievals.map((r) => {
+    const documents = (r.documents ?? []).map((d) => d.id ?? `"${d.content.slice(0, 40)}"`);
+    const shown = documents.slice(0, 10).join(", ") + (documents.length > 10 ? ", ..." : "");
+    return `"${r.query ?? "(none recorded)"}": [${shown}]`;
+  }).join("; ");
+}
+function requireTopK(topK) {
+  if (topK !== void 0 && (!Number.isInteger(topK) || topK < 1)) {
+    throw new TypeError(`retrieved: topK must be a positive integer, got ${topK}`);
+  }
+}
 
 // src/agent-task/checks/recorder.ts
 var Recorder = class {
   constructor(locate) {
     this.records = [];
     this.pending = [];
+    this.negating = false;
     this.locate = locate;
   }
+  /**
+   * Run `fn` with every assertion it records negated (`t.not.*`): a pass
+   * becomes a fail and a fail becomes a pass. Outcomes that are not verdicts
+   * (`unsupported`, `error`) keep their outcome, so missing evidence can never
+   * become a pass by negation. Only synchronous assertions are negatable,
+   * which keeps the scope from leaking into a later record.
+   */
+  negated(fn) {
+    const previous = this.negating;
+    this.negating = true;
+    try {
+      fn();
+    } finally {
+      this.negating = previous;
+    }
+  }
   /**
    * 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,
@@ -3622,7 +4226,7 @@ var Recorder = class {
    */
   record(id, pass, reasoning, extra) {
     const location = extra?.location ?? (this.locate ? this.locate(new Error().stack ?? "") : void 0);
-    this.records.push({
+    const result = {
       id,
       pass,
       reasoning,
@@ -3631,13 +4235,29 @@ var Recorder = class {
       received: extra?.received,
       evaluator_type: extra?.evaluator_type,
       judge: extra?.judge,
+      embedding: extra?.embedding,
       outcome: extra?.outcome
-    });
+    };
+    this.records.push(this.negating ? negate(result) : result);
   }
   get all() {
     return this.records;
   }
 };
+function negate(result) {
+  const negated = {
+    ...result,
+    id: `not.${result.id}`,
+    expected: result.expected === void 0 ? void 0 : `not ${result.expected}`
+  };
+  if (result.outcome === "unsupported" || result.outcome === "error") return negated;
+  return {
+    ...negated,
+    pass: !result.pass,
+    reasoning: result.pass ? `expected ${result.id} not to hold, but it did` : "",
+    outcome: result.outcome === void 0 ? void 0 : result.pass ? "fail" : "pass"
+  };
+}
 
 // src/agent-task/checks/compact.ts
 import { createHash as createHash4 } from "crypto";
@@ -3872,12 +4492,18 @@ async function runTraceChecks(args) {
   const view = new TraceView(args.snapshot);
   const locate = args.moduleUrl && args.displayFile ? (stack) => parseCheckLocation(stack, args.moduleUrl, args.displayFile) : void 0;
   const taskMeta = readTaskMeta(args.task);
+  const embedding = args.embedding ? { ...args.embedding, ...args.embedding.tracer ? {} : optionalTracer(args.judgeTracer) } : { client: createEmbeddingClient(), ...optionalTracer(args.judgeTracer) };
   const results = await Promise.all(
-    registry.map((check) => runOneCheck(check, args, view, taskMeta, locate))
+    registry.map((check) => runOneCheck(check, args, embedding, view, taskMeta, locate))
   );
   return results;
 }
-async function runOneCheck(check, args, view, taskMeta, locate) {
+function optionalTracer(tracer) {
+  if (!tracer) return {};
+  const candidate = tracer;
+  return typeof candidate.step === "function" && typeof candidate.score === "function" ? { tracer: candidate } : {};
+}
+async function runOneCheck(check, args, embedding, view, taskMeta, locate) {
   const runCheck = async () => {
     const rec = new Recorder(locate);
     const reads = trackDeliverableReads(args.deliverables);
@@ -3901,7 +4527,8 @@ async function runOneCheck(check, args, view, taskMeta, locate) {
         ...args.historyUnavailableReason ? { historyUnavailable: args.historyUnavailableReason } : {}
       },
       args.judgeTracer,
-      args.judgeTools
+      args.judgeTools,
+      embedding
     );
     let thrownLocation;
     try {
@@ -3921,9 +4548,11 @@ async function runOneCheck(check, args, view, taskMeta, locate) {
     const pass = failed.length === 0;
     const outcome = rollUpCheckOutcome(failed);
     const judged = rec.all.filter(isJudgedAssertion);
-    const reasoning = failed.length > 0 ? failed.map((r) => r.reasoning || r.id).join("; ") : judged.length > 0 ? judged.map((r) => r.reasoning).filter(Boolean).join("; ") || "passed" : rec.all.length > 0 ? "passed" : "no assertions recorded";
+    const semantic = rec.all.filter((r) => r.evaluator_type === "embedding");
+    const reasoning = failed.length > 0 ? failed.map((r) => r.reasoning || r.id).join("; ") : judged.length > 0 || semantic.length > 0 ? [...judged, ...semantic].map((r) => r.reasoning).filter(Boolean).join("; ") || "passed" : 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;
+    const embeddingMeta = rec.all.find((r) => r.embedding)?.embedding;
     return {
       id: check.id,
       pass,
@@ -3931,6 +4560,7 @@ async function runOneCheck(check, args, view, taskMeta, locate) {
       evaluator_type: deriveEvaluatorType(rec.all),
       ...outcome ? { outcome } : {},
       ...judge ? { judge } : {},
+      ...embeddingMeta ? { embedding: embeddingMeta } : {},
       ...location ? { location } : {},
       ...args.displayFile ? { source_file: args.displayFile } : {},
       ...rec.all.length > 0 ? { assertions: rec.all.map((a) => ({ ...a })) } : {},
@@ -3960,19 +4590,27 @@ function isJudgedAssertion(assertion) {
 function deriveEvaluatorType(assertions) {
   let sawLlm = false;
   let sawAgent = false;
+  let sawEmbedding = false;
   let sawDeterministic = false;
   for (const assertion of assertions) {
     if (isJudgedAssertion(assertion)) {
       if (assertion.evaluator_type === "agent") sawAgent = true;
       else sawLlm = true;
+    } else if (assertion.evaluator_type === "embedding") {
+      sawEmbedding = true;
     } else {
       sawDeterministic = true;
     }
   }
-  if (!sawLlm && !sawAgent) return "code";
-  if (sawDeterministic) return "mixed";
-  if (sawAgent && !sawLlm) return "agent";
-  return "llm";
+  const evaluatorKinds = [sawLlm, sawAgent, sawEmbedding].filter(Boolean).length;
+  if (evaluatorKinds === 0 && !sawDeterministic) return "code";
+  if (evaluatorKinds === 1 && !sawDeterministic) {
+    if (sawAgent) return "agent";
+    if (sawEmbedding) return "embedding";
+    return "llm";
+  }
+  if (evaluatorKinds > 0) return "mixed";
+  return "code";
 }
 function summarizeCheckForSpan(result) {
   const check = result;
@@ -3981,6 +4619,7 @@ function summarizeCheckForSpan(result) {
     text: reasoning,
     verdict: {
       pass: check.pass,
+      ...check.outcome ? { outcome: check.outcome } : {},
       reasoning,
       evaluator_type: check.evaluator_type,
       ...check.judge ? { judge_model: check.judge.model } : {},
@@ -4017,6 +4656,7 @@ async function loadAndRunFlowChecks(checksPath, args, brokenDeliverables = {}) {
     ...args.judgeTools ? { judgeTools: args.judgeTools } : {},
     ...args.historyPlane ? { historyPlane: args.historyPlane } : {},
     ...args.judgeTracer ? { judgeTracer: args.judgeTracer } : {},
+    ...args.embedding ? { embedding: args.embedding } : {},
     moduleUrl,
     displayFile: basename(checksPath)
   });
@@ -4817,6 +5457,7 @@ function deriveCapabilities(observations, hierarchyAmbiguous) {
   const hasMessages = observations.some(
     (o) => o.type === "GENERATION" && o.messages && o.messages.length > 0
   );
+  const retrievals = observations.filter((o) => o.type === "RETRIEVER");
   return {
     messages: hasMessages ? "available" : "unavailable",
     tools: hasType("TOOL") ? "available" : "unavailable",
@@ -4829,7 +5470,8 @@ function deriveCapabilities(observations, hierarchyAmbiguous) {
     // Usage is attributed to turns through parentSpanId; with an ambiguous
     // step id the chain is broken, so a per-turn or per-run sum could
     // silently drop turns.
-    usage: !observations.some((o) => o.usage !== void 0) ? "unavailable" : hierarchyAmbiguous ? "partial" : "available"
+    usage: !observations.some((o) => o.usage !== void 0) ? "unavailable" : hierarchyAmbiguous ? "partial" : "available",
+    retrieval: retrievals.length === 0 ? "unavailable" : retrievals.some((o) => documentsFromObservation(o) !== void 0) ? "available" : "partial"
   };
 }
 function usageFrom(params) {
@@ -4845,6 +5487,7 @@ function createProjectionTee(real) {
   const observations = [];
   const pending = /* @__PURE__ */ new Map();
   const realIdByTeeId = /* @__PURE__ */ new Map();
+  const exportedSpanIds = /* @__PURE__ */ new Set();
   const teeIdByRealStepId = /* @__PURE__ */ new Map();
   const ambiguousRealStepIds = /* @__PURE__ */ new Set();
   const activeStep = new AsyncLocalStorage();
@@ -4882,6 +5525,7 @@ function createProjectionTee(real) {
     } else if (params?.output !== void 0) {
       obs.output = params.output;
     }
+    if (p.type === "RETRIEVER" && p.input !== void 0) obs.input = p.input;
     if (p.type === "GENERATION" && params?.output != null) {
       const text = extractText(params.output);
       if (text !== "") {
@@ -4921,6 +5565,7 @@ function createProjectionTee(real) {
               ambiguousRealStepIds.add(realSpanId);
             } else {
               teeIdByRealStepId.set(realSpanId, obsSpanId);
+              exportedSpanIds.add(realSpanId);
             }
           }
           return activeStep.run(obsSpanId, () => fn(realSpanId));
@@ -4980,6 +5625,9 @@ function createProjectionTee(real) {
       realIdByTeeId.delete(spanId);
       try {
         real.endSpan(realId, endParams);
+        if (realId != null && realId !== spanId) {
+          exportedSpanIds.add(realId);
+        }
       } catch {
       }
     },
@@ -5009,7 +5657,32 @@ function createProjectionTee(real) {
       }
     },
     async traceRetriever(query, fn) {
-      return real.traceRetriever(query, fn);
+      const obsSpanId = recordStart({
+        step_name: "retrieve",
+        observation_type: "RETRIEVER",
+        input: { query }
+      });
+      const start = monotonicNowMs();
+      try {
+        const result = await real.traceRetriever(query, fn);
+        const documents = parseRetrievedDocuments(result);
+        complete(obsSpanId, {
+          latency_ms: round3(monotonicNowMs() - start),
+          // Recognized results are stored normalized so every reader sees one
+          // typed shape. Anything else passes through raw, and the retrieval
+          // capability derives "partial" from it.
+          output: documents !== void 0 ? { documents } : 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 traceChain(name, fn) {
       return real.traceChain(name, fn);
@@ -5046,14 +5719,22 @@ function createProjectionTee(real) {
         observations: [...observations]
       };
     },
-    injectObservations(injected) {
+    injectObservations(injected, opts) {
       observations.push(...injected);
+      if (opts?.remote !== false) {
+        for (const observation of injected) {
+          exportedSpanIds.add(observation.spanId);
+        }
+      }
       observations.sort((a, b) => {
         const at = a.startedAt ?? "";
         const bt = b.startedAt ?? "";
         if (at !== bt) return at < bt ? -1 : 1;
         return a.spanId < b.spanId ? -1 : 1;
       });
+    },
+    getExportedSpanIds() {
+      return new Set(exportedSpanIds);
     }
   };
 }
@@ -6065,6 +6746,11 @@ function resolveJudgeToolsForTask(runLevel, taskLevel, taskDir) {
   if (!layered?.mcp) return layered;
   return { mcp: resolveMcpServerPaths(layered.mcp, taskDir) };
 }
+function buildEmbeddingRuntime(runLevel, taskLevel) {
+  const provider = resolveEmbeddingConfig(runLevel, taskLevel);
+  if (!provider) return void 0;
+  return { provider, client: createEmbeddingClient() };
+}
 async function runTask(taskDir, options) {
   const loaded = options?.loaded ?? await loadTask(taskDir);
   const trace2 = options?.tracing;
@@ -6082,19 +6768,19 @@ async function runTask(taskDir, options) {
       const phase1 = await captureExecution(loaded, options, traceContext);
       const canonical = await readCanonicalSnapshot(
         trace2,
-        phase1.replayObservationFloor
+        phase1.exportedSpanIds
       );
       if (canonical) phase1.snapshot = canonical;
       return evaluate(loaded, options, phase1, traceContext);
     }
   );
 }
-async function readCanonicalSnapshot(trace2, minObservations) {
+async function readCanonicalSnapshot(trace2, exportedSpanIds, opts = {}) {
   if (!trace2.taskRunId) return null;
   const endpoint = process.env.AGENT_TASK_TRACE_ENDPOINT;
   const authToken = process.env.APO_AUTH_TOKEN;
   if (!endpoint || !authToken) return null;
-  const deadlineMs = 3e4;
+  const deadlineMs = opts.deadlineMs ?? 3e4;
   const start = Date.now();
   try {
     let snapshot = await readTaskRunProjection({
@@ -6102,25 +6788,17 @@ async function readCanonicalSnapshot(trace2, minObservations) {
       authToken,
       taskRunId: trace2.taskRunId,
       deadlineMs,
-      // Fresh-run readback: the run row was pre-created by the caller/executor
-      // flow, and the subprocess-exported trace may still be in flight when
-      // the checks phase starts — a 409 "no trace yet" must wait for the
-      // claim, not fall back to a local snapshot that cannot see the
-      // subprocess's spans.
-      // Fresh-run readback: the run row was pre-created by the caller/executor
-      // flow, and the subprocess-exported trace may still be in flight when
-      // the checks phase starts — a 409 "no trace yet" must wait for the
-      // claim, not fall back to a local snapshot that cannot see the
-      // subprocess's spans.
+      // Fresh-run readback: the trace claim may still be landing, so the
+      // 409 must be waited out rather than fallen back from.
       retryNoTrace: true
     });
-    while (minObservations !== void 0 && snapshot.observations.length < minObservations) {
+    while (!containsAllSpanIds(snapshot, exportedSpanIds)) {
       const remaining = deadlineMs - (Date.now() - start);
       if (remaining <= 0) {
         console.error(
-          `[AgentTask] Projection still missing replayed observations after ${deadlineMs}ms (${snapshot.observations.length}/${minObservations}); continuing with the current snapshot`
+          `[AgentTask] Projection missing ${countMissingSpanIds(snapshot, exportedSpanIds)}/${exportedSpanIds.size} spans the run exported after ${deadlineMs}ms; using the local snapshot`
         );
-        break;
+        return null;
       }
       await new Promise((resolve5) => setTimeout(resolve5, 500));
       snapshot = await readTaskRunProjection({
@@ -6139,6 +6817,27 @@ async function readCanonicalSnapshot(trace2, minObservations) {
     return null;
   }
 }
+function containsAllSpanIds(snapshot, required) {
+  if (required.size === 0) return true;
+  const present = new Set(
+    snapshot.observations.map((observation) => observation.spanId)
+  );
+  for (const id of required) {
+    if (!present.has(id)) return false;
+  }
+  return true;
+}
+function countMissingSpanIds(snapshot, required) {
+  if (required.size === 0) return 0;
+  const present = new Set(
+    snapshot.observations.map((observation) => observation.spanId)
+  );
+  let missing = 0;
+  for (const id of required) {
+    if (!present.has(id)) missing++;
+  }
+  return missing;
+}
 async function executeAdapterRun(loaded, options, rawTrace, continueWith) {
   const {
     task: task2,
@@ -6273,7 +6972,7 @@ async function executeAdapterRun(loaded, options, rawTrace, continueWith) {
                 endpoint: process.env.AGENT_TASK_TRACE_ENDPOINT
               })
             );
-            tee.injectObservations(replay.observations);
+            tee.injectObservations(replay.observations, { remote: replay.exported });
           }
           return await continueWith({
             collected,
@@ -6281,7 +6980,8 @@ async function executeAdapterRun(loaded, options, rawTrace, continueWith) {
             runConfiguration,
             replay,
             trace: trace2,
-            getSnapshot: () => tee.getSnapshot()
+            getSnapshot: () => tee.getSnapshot(),
+            getExportedSpanIds: () => tee.getExportedSpanIds()
           });
         } catch (error) {
           throw withRunConfiguration(error, runConfiguration);
@@ -6334,6 +7034,7 @@ async function executeLoadedTask(loaded, options, rawTrace, traceRunId) {
       async () => {
         const judgeConfig = resolveJudgeConfig(options?.judge, task2.judge);
         const judgeTools = resolveJudgeToolsForTask(options?.judgeTools, task2.judgeTools, absoluteDir);
+        const embeddingRuntime = buildEmbeddingRuntime(options?.embedding, task2.embedding);
         const historyPlane = await freezeHistoryPlaneFromEnv(task2.id);
         if (!inlineChecks) {
           return loadAndRunFlowChecks(
@@ -6346,7 +7047,8 @@ async function executeLoadedTask(loaded, options, rawTrace, traceRunId) {
               ...judgeConfig ? { judgeConfig } : {},
               ...judgeTools ? { judgeTools } : {},
               judgeTracer: trace2,
-              ...historyPlane ? { historyPlane } : {}
+              ...historyPlane ? { historyPlane } : {},
+              ...embeddingRuntime ? { embedding: embeddingRuntime } : {}
             },
             validationResults.brokenDeliverables
           );
@@ -6363,6 +7065,7 @@ async function executeLoadedTask(loaded, options, rawTrace, traceRunId) {
           ...judgeTools ? { judgeTools } : {},
           judgeTracer: trace2,
           ...historyPlane ? { historyPlane } : {},
+          ...embeddingRuntime ? { embedding: embeddingRuntime } : {},
           moduleUrl,
           displayFile: evalFileName
         });
@@ -6386,11 +7089,9 @@ async function captureExecution(loaded, options, rawTrace) {
     collected: outcome.collected,
     transcriptTurns: outcome.transcriptTurns,
     runConfiguration: outcome.runConfiguration,
-    // Freeze the snapshot before the root span ends — Phase 2 reads it.
+    // Freeze the snapshot before the root span ends: Phase 2 reads it.
     snapshot: outcome.getSnapshot(),
-    // The floor for the canonical read-back: everything the local snapshot
-    // holds (runner spans + replayed observations) should project remotely.
-    ...outcome.replay ? { replayObservationFloor: outcome.getSnapshot().observations.length } : {}
+    exportedSpanIds: outcome.getExportedSpanIds()
   }));
 }
 async function evaluate(loaded, options, phase1, judgeTracer) {
@@ -6411,9 +7112,9 @@ async function evaluate(loaded, options, phase1, judgeTracer) {
   );
   const judgeConfig = resolveJudgeConfig(options?.judge, task2.judge);
   const judgeTools = resolveJudgeToolsForTask(options?.judgeTools, task2.judgeTools, absoluteDir);
+  const embeddingRuntime = buildEmbeddingRuntime(options?.embedding, task2.embedding);
   const historyPlane = await freezeHistoryPlaneFromEnv(task2.id);
   const runChecks = async () => inlineChecks ? runTraceChecks({
-    ...judgeTools ? { judgeTools } : {},
     snapshot: phase1.snapshot,
     deliverables,
     files,
@@ -6422,6 +7123,7 @@ async function evaluate(loaded, options, phase1, judgeTracer) {
     ...judgeTools ? { judgeTools } : {},
     ...judgeTracer ? { judgeTracer } : {},
     ...historyPlane ? { historyPlane } : {},
+    ...embeddingRuntime ? { embedding: embeddingRuntime } : {},
     moduleUrl,
     displayFile: evalFileName
   }) : loadAndRunFlowChecks(
@@ -6434,7 +7136,8 @@ async function evaluate(loaded, options, phase1, judgeTracer) {
       ...judgeConfig ? { judgeConfig } : {},
       ...judgeTools ? { judgeTools } : {},
       ...judgeTracer ? { judgeTracer } : {},
-      ...historyPlane ? { historyPlane } : {}
+      ...historyPlane ? { historyPlane } : {},
+      ...embeddingRuntime ? { embedding: embeddingRuntime } : {}
     },
     validationResults.brokenDeliverables
   );
@@ -6994,13 +7697,23 @@ function createOtelAgentTaskTraceClient(config) {
     if (params.provider) {
       span.setAttribute("gen_ai.provider.name", params.provider);
     }
+    if (params.api_provider) {
+      span.setAttribute("apo.llm.api_provider", params.api_provider);
+    }
+    if (params.serving_host) {
+      span.setAttribute("apo.llm.serving_host", params.serving_host);
+    }
+    if (params.observation_type === "GENERATION") {
+      span.setAttribute("apo.llm.request_kind", "request");
+    }
     if (params.route) {
       span.setAttribute("apo.llm.route", params.route);
     }
     const isTool = params.observation_type === "TOOL";
+    const usesToolChannels = isTool || params.observation_type === "RETRIEVER";
     if (params.input) {
-      if (isTool) {
-        if (params.tool_name) {
+      if (usesToolChannels) {
+        if (isTool && params.tool_name) {
           span.setAttribute("gen_ai.tool.name", params.tool_name);
         }
         span.setAttribute("gen_ai.tool.call.arguments", JSON.stringify(params.input));
@@ -7034,7 +7747,7 @@ function createOtelAgentTaskTraceClient(config) {
     const latency = params.latency_ms ?? round32(monotonicNowMs2() - active.startedAt);
     active.span.setAttribute("latency_ms", latency);
     if (params.output !== void 0) {
-      if (active.observationType === "TOOL") {
+      if (active.observationType === "TOOL" || active.observationType === "RETRIEVER") {
         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) {
@@ -7093,6 +7806,12 @@ function createOtelAgentTaskTraceClient(config) {
     if (params.provider) {
       active.span.setAttribute("gen_ai.provider.name", params.provider);
     }
+    if (params.serving_host) {
+      active.span.setAttribute("apo.llm.serving_host", params.serving_host);
+    }
+    if (params.api_provider) {
+      active.span.setAttribute("apo.llm.api_provider", params.api_provider);
+    }
     if (params.route) {
       active.span.setAttribute("apo.llm.route", params.route);
     }
@@ -7129,6 +7848,9 @@ function createOtelAgentTaskTraceClient(config) {
       if (params.tags?.length) {
         rootSpan.setAttribute("apo.run.tags", JSON.stringify(params.tags));
       }
+      if (params.environment) {
+        rootSpan.setAttribute("apo.run.environment", params.environment);
+      }
       const rootMeta = params.rootSpan?.metadata;
       const taskRunId = params.taskRunId ?? rootMeta?.["apo.task.run.id"] ?? params.run_metadata?.["agent_task_run_id"];
       if (taskRunId) {
@@ -7424,15 +8146,55 @@ async function loadTaskRuntime(_taskDir) {
     judge: resolveJudgeFromEnv(),
     // Env/file layer for MCP evidence servers (APO_JUDGE_MCP) — seeds the
     // run-level config, so explicit runTask({ judgeTools }) always wins.
-    judgeTools: await resolveJudgeToolsFromEnv()
+    judgeTools: await resolveJudgeToolsFromEnv(),
+    embedding: resolveEmbeddingFromEnv()
   };
 }
+function resolveEmbeddingFromEnv() {
+  const model = process.env.APO_EMBEDDING_MODEL?.trim();
+  if (model) {
+    return {
+      model,
+      ...process.env.APO_EMBEDDING_BASE_URL ? { baseURL: process.env.APO_EMBEDDING_BASE_URL } : {},
+      ...process.env.APO_EMBEDDING_API_KEY ? { apiKey: process.env.APO_EMBEDDING_API_KEY } : {},
+      ...process.env.APO_EMBEDDING_DIMENSIONS ? { dimensions: parseDimensions(process.env.APO_EMBEDDING_DIMENSIONS) } : {}
+    };
+  }
+  if (process.env.OPENROUTER_API_KEY) {
+    return {
+      model: "openai/text-embedding-3-small",
+      // The endpoint is named here, never defaulted at request time — a
+      // host is only ever contacted because a layer resolved it.
+      baseURL: process.env.OPENROUTER_BASE_URL ?? "https://openrouter.ai/api/v1",
+      apiKey: process.env.OPENROUTER_API_KEY
+    };
+  }
+  if (process.env.OPENAI_API_KEY) {
+    return {
+      model: "text-embedding-3-small",
+      apiKey: process.env.OPENAI_API_KEY,
+      baseURL: process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1"
+    };
+  }
+  return void 0;
+}
+function parseDimensions(raw) {
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
+}
 function resolveJudgeFromEnv() {
-  const openRouterModel = process.env.OPENROUTER_MODEL;
-  const openAIModel = process.env.OPENAI_MODEL;
-  const anthropicModel = process.env.ANTHROPIC_MODEL;
-  const model = openRouterModel ?? openAIModel ?? anthropicModel;
+  const judgeOverride = firstEnvValue("AGENT_TASK_JUDGE_MODEL");
+  const openRouterModel = firstEnvValue("AGENT_TASK_OPENROUTER_MODEL", "OPENROUTER_MODEL");
+  const openAIModel = firstEnvValue("OPENAI_MODEL");
+  const anthropicModel = firstEnvValue("ANTHROPIC_MODEL", "AGENT_TASK_ANTHROPIC_MODEL");
+  const model = judgeOverride ?? openRouterModel ?? openAIModel ?? anthropicModel;
   if (!model) return void 0;
+  if (judgeOverride && !openRouterModel && !openAIModel && !anthropicModel) {
+    return {
+      model,
+      ...process.env.APO_JUDGE_MODE?.trim() === "cascade" ? { mode: "cascade" } : {}
+    };
+  }
   return {
     model,
     baseURL: openRouterModel ? process.env.OPENROUTER_BASE_URL : openAIModel ? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1" : process.env.ANTHROPIC_BASE_URL ?? "https://api.anthropic.com",
@@ -7453,6 +8215,13 @@ function resolveJudgeFromEnv() {
     ...process.env.APO_JUDGE_MODE?.trim() === "cascade" ? { mode: "cascade" } : {}
   };
 }
+function firstEnvValue(...names) {
+  for (const name of names) {
+    const value = process.env[name]?.trim();
+    if (value) return value;
+  }
+  return void 0;
+}
 async function runTaskDir(taskDir, options) {
   const [loaded, runtime] = await Promise.all([
     loadTask(taskDir),
@@ -7738,14 +8507,17 @@ export {
   compactChecksForSubmission,
   connectMcpServers,
   contentSha256,
+  cosineSimilarity,
   createApoAnthropic,
   createApoOpenAI,
   createApoTracer,
+  createEmbeddingClient,
   defineAdapter,
   defineTask,
   describe2 as describe,
   detectTranscriptSource,
   discoverAgentTaskDirs,
+  embeddingSettingsSignature,
   equals,
   evaluateComputeExpression,
   expandSecretPlaceholders,
@@ -7777,6 +8549,7 @@ export {
   resetTaskRegistry,
   resetTaskSteers,
   resetTaskTurn,
+  resolveEmbeddingConfig,
   resolveMcpServerPaths,
   resolveOtlpTracesUrl,
   resolveTurn,