@apo-ai/sdk 0.16.1 → 0.17.0

package/dist/agent-task/integrations/ai-sdk.d.ts

@@ -1,4 +1,4 @@
-import { A as AgentTaskTraceContext } from '../../tracing-CEucJqQI.js';
+import { A as AgentTaskTraceContext } from '../../tracing-CDeEfMis.js';
 
 /**
  * Vercel AI SDK tracing integration for apo.

package/dist/agent-task/integrations/anthropic.d.ts

@@ -1,4 +1,4 @@
-import { A as AgentTaskTraceContext } from '../../tracing-CEucJqQI.js';
+import { A as AgentTaskTraceContext } from '../../tracing-CDeEfMis.js';
 
 /**
  * Anthropic JS SDK tracing integration for apo.

package/dist/agent-task/integrations/anthropic.js

@@ -2,8 +2,8 @@
 // Do not edit by hand — edit the src/ originals and rebuild.
 import {
   createApoAnthropic
-} from "../../chunk-4BQSCD6T.js";
-import "../../chunk-JN7RHBTS.js";
+} from "../../chunk-6U6V7VKZ.js";
+import "../../chunk-KWIYQSWK.js";
 export {
   createApoAnthropic
 };

package/dist/agent-task/integrations/openai.d.ts

@@ -1,4 +1,4 @@
-import { A as AgentTaskTraceContext } from '../../tracing-CEucJqQI.js';
+import { A as AgentTaskTraceContext } from '../../tracing-CDeEfMis.js';
 
 /**
  * OpenAI JS SDK tracing integration for apo.

package/dist/agent-task/integrations/openai.js

@@ -2,8 +2,8 @@
 // Do not edit by hand — edit the src/ originals and rebuild.
 import {
   createApoOpenAI
-} from "../../chunk-NSMKSPBU.js";
-import "../../chunk-JN7RHBTS.js";
+} from "../../chunk-Z7DVZ34X.js";
+import "../../chunk-KWIYQSWK.js";
 export {
   createApoOpenAI
 };

package/dist/agent-task/public.d.ts

@@ -1,4 +1,4 @@
-import { A as AgentTaskTraceContext, a as AgentTaskTraceOptions } from '../tracing-CEucJqQI.js';
+import { A as AgentTaskTraceContext, E as EmbeddingTracer, a as AgentTaskTraceOptions } from '../tracing-CDeEfMis.js';
 export { CreateApoTracerOptions, createApoTracer } from './integrations/ai-sdk.js';
 export { CreateApoOpenAIOptions, createApoOpenAI } from './integrations/openai.js';
 export { CreateApoAnthropicOptions, createApoAnthropic } from './integrations/anthropic.js';
@@ -52,6 +52,13 @@ interface TraceProjectionCapabilities {
      * was projected: absent reads as `unavailable`.
      */
     usage?: EvidenceAvailability;
+    /**
+     * Retrieved documents on `RETRIEVER` observations. Optional for snapshots
+     * written before retrieval was projected: absent reads as `unavailable`.
+     * `partial` means retrievals were observed but none returned a
+     * recognizable document list.
+     */
+    retrieval?: EvidenceAvailability;
 }
 /**
  * Token counts one observation reported. Each dimension is present only when
@@ -61,6 +68,43 @@ interface TraceProjectionUsage {
     inputTokens?: number;
     outputTokens?: number;
 }
+/**
+ * Observed serving identity for one generation (issue #307). Each field is
+ * present only when the source reported it; unknown stays undefined, never a
+ * placeholder string. The provider an OpenAI-compatible call reached can
+ * differ from the host that executed inference; both survive here.
+ */
+interface TraceProjectionServing {
+    /** Response model when reported, else the normalized model. */
+    model?: string;
+    instrumentationProvider?: string;
+    /** The service the harness called, e.g. `openrouter`. */
+    apiProvider?: string;
+    /** The organization that executed the inference, e.g. `baseten`. */
+    servingHost?: string;
+    /** The requested named selection policy, e.g. `nitro`. */
+    route?: string;
+    requestedServiceTier?: string;
+    /** The priority class actually served. */
+    serviceTier?: string;
+    requestModel?: string;
+    responseModel?: string;
+}
+/**
+ * Speed evidence for one generation (issue #307). Whole-call rate divides
+ * output tokens by the full request window; streaming rate divides by the
+ * decode window after first content. Absent fields were not measurable.
+ */
+interface TraceProjectionRates {
+    /** Elapsed milliseconds from request start to first generated content. */
+    timeToFirstTokenMs?: number;
+    wholeCallOutputTokensPerSecond?: number;
+    streamingOutputTokensPerSecond?: number;
+    /** Which output-token numerator the rates describe. */
+    outputTokenScope?: "text" | "all_output" | "unknown";
+    /** Why a streaming rate is absent, when it is. */
+    streamingUnavailableReason?: "missing_timing" | "invalid_timing" | "missing_usage" | "scope_mismatch" | "unknown_scope" | "incomplete_call" | "aggregate_only";
+}
 /** One chat message reconstructed from a generation observation. */
 interface TraceProjectionMessage {
     role: "system" | "user" | "assistant" | "tool";
@@ -91,6 +135,21 @@ interface TraceProjectionObservation {
     messages?: readonly TraceProjectionMessage[];
     /** Token usage this observation reported. Absent when none was recorded. */
     usage?: TraceProjectionUsage;
+    /**
+     * Observed serving identity (issue #307). Optional: snapshots written
+     * before the feature carry none, and non-generation observations never
+     * carry one.
+     */
+    serving?: TraceProjectionServing;
+    /** Speed evidence (issue #307). Optional; same snapshot rules as serving. */
+    rates?: TraceProjectionRates;
+    /**
+     * Whether this observation accounts for one physical API request
+     * (`"request"`) or a multi-request wrapper (`"aggregate"`). Absent on
+     * snapshots written before the feature; unknown accounting is omitted
+     * rather than guessed.
+     */
+    requestAccounting?: "request" | "aggregate";
     metadata?: Readonly<Record<string, unknown>>;
 }
 /** Trace-level facts. All timing is optional; absence is honest. */
@@ -116,6 +175,27 @@ interface TraceProjectionSnapshot {
     observations: readonly TraceProjectionObservation[];
 }
 
+/**
+ * Retrieval evidence: the boundary between whatever a retriever returns and
+ * the typed documents assertions match on.
+ *
+ * A retrieval is an action with content: a query in, ranked documents out.
+ * Retrievers return wildly different shapes, so the projection tee parses the
+ * return value once at capture into the OpenInference document names (id,
+ * score, content) and readers only ever see the typed result. Snapshots that
+ * did not pass through the tee (canonical backend projections, injected
+ * replay observations) go through the same parser at read time, so both
+ * paths agree on what counts as recognized.
+ */
+
+/** One retrieved document. Attribute names follow the OpenInference spec. */
+interface TraceProjectionDocument {
+    /** Stable corpus id when the retriever reports one. Absent for content-only retrievers. */
+    id?: string;
+    score?: number;
+    content: string;
+}
+
 /**
  * TraceView — typed, capability-gated, derived access over a
  * {@link TraceProjectionSnapshot}. This is the read model the projection-first
@@ -172,6 +252,21 @@ interface TraceToolCall {
     status: ObservationStatus;
     startedAt?: string;
 }
+/** A retrieval derived from a `RETRIEVER` observation. */
+interface TraceRetrieval {
+    spanId: string;
+    /** The query the retriever ran with, when recorded. */
+    query?: string;
+    /**
+     * The returned documents, in retriever rank order, when the result shape was
+     * recognized. Absent means the retrieval happened but its documents are
+     * unknown: negative assertions must fail closed on it, never read it as
+     * "nothing retrieved".
+     */
+    documents?: readonly TraceProjectionDocument[];
+    status: ObservationStatus;
+    startedAt?: string;
+}
 /** A skill load derived from a `SKILL` observation. */
 interface TraceSkillLoad {
     spanId: string;
@@ -227,6 +322,8 @@ declare class TraceView {
     get toolCalls(): readonly TraceToolCall[];
     /** Tool names in invocation order with deterministic span-ID tie-breaking. */
     get toolNamesInOrder(): readonly string[];
+    /** Retrievals derived from `RETRIEVER` observations, in invocation order. */
+    get retrievals(): readonly TraceRetrieval[];
     /** Skill loads derived from `SKILL` observations, in invocation order. */
     get skillLoads(): readonly TraceSkillLoad[];
     /** Subagent delegations derived from `AGENT` observations, in invocation order. */
@@ -592,6 +689,139 @@ declare function getTaskSteers(): SteerSpec[];
 /** Clear registrations (loadTask use — mirrors resetTaskTurn). */
 declare function resetTaskSteers(): void;
 
+/**
+ * Embedding-similarity grading, the deterministic third leg of the check
+ * vocabulary (exact/fuzzy matchers, `t.judge`, `t.agent`). Calls any
+ * OpenAI-compatible `/embeddings` endpoint (OpenRouter, OpenAI direct, local
+ * Ollama/vLLM/LM Studio), L2-normalizes both vectors, and compares with
+ * cosine similarity: the same inputs under the same config grade the same
+ * every time, unlike an LLM judge.
+ *
+ * Every verdict records a sacreBLEU-style settings signature
+ * (`model:1536d:cosine:apo-v1`) because cosine scales are model-bound: a
+ * threshold that means "paraphrase" on one embedding model can mean
+ * "unrelated" on another. The signature is the contract.
+ */
+/** HTTP embedding config for any OpenAI-compatible `/embeddings` endpoint. */
+type EmbeddingConfig = {
+    /**
+     * Embedding model id in the provider's namespace, e.g.
+     * `"openai/text-embedding-3-small"` (OpenRouter) vs
+     * `"text-embedding-3-small"` (OpenAI direct). Never reuse a chat model id.
+     */
+    model: string;
+    /** Endpoint base; defaults per provider resolution. Set for local servers. */
+    baseURL?: string;
+    /** Optional for local endpoints (Ollama and friends need none). */
+    apiKey?: string;
+    /**
+     * Best-effort Matryoshka truncation (models that support it only). The
+     * dimensionality actually returned is always what gets recorded and
+     * compared; a 400 naming `dimensions` is retried once without it.
+     */
+    dimensions?: number;
+};
+/**
+ * Full escape hatch: bring any embedder, from Cohere/Voyage request dialects
+ * to an in-process transformers.js pipeline, as a function. Programmatic layer
+ * only (`runTask({ embedding })`); env and task layers carry the HTTP shape.
+ */
+type EmbeddingProvider = EmbeddingConfig | {
+    embed: (input: string[]) => Promise<number[][]>;
+};
+/**
+ * Metadata recorded on an assertion graded by embedding similarity. The
+ * mirror of `JudgeMetadata`: what graded, under which pinned settings, at
+ * what cost, so a similarity number is interpretable years later.
+ */
+type EmbeddingMetadata = {
+    /** The requested model id, e.g. `openai/text-embedding-3-small`. */
+    model: string;
+    /** The model the provider reports serving (response `model` field). */
+    served_model?: string;
+    /** Vector dimensionality actually returned. */
+    dimensions: number;
+    /** Cosine similarity, rounded to 4 decimals. */
+    similarity: number;
+    threshold: number;
+    metric: "cosine";
+    /** `model:1536d:cosine:apo-v1`, everything that can move the number. */
+    settings_hash: string;
+    tokens?: {
+        input: number;
+    };
+    latency_ms?: number;
+    /** Deep link to this call's EMBEDDING observation in the trace view. */
+    span_id?: string;
+    /** Short previews of the compared texts, for string-only renderers. */
+    value_preview?: string;
+    reference_preview?: string;
+};
+/**
+ * Resolved per-call config: the HTTP shape or a custom embed fn, plus the
+ * effective model id used in signatures and error messages.
+ */
+type ResolvedEmbeddingProvider = {
+    config: EmbeddingConfig;
+    custom?: undefined;
+} | {
+    config?: undefined;
+    custom: {
+        embed: (input: string[]) => Promise<number[][]>;
+    };
+};
+/**
+ * Merge an embedding config override onto a base provider, most specific
+ * layer winning, the same field-by-field merge `resolveJudgeConfig` uses,
+ * so a partial layer (`{ dimensions }`, `{ apiKey }`) applies over the base
+ * instead of being dropped. An override carrying a `model` always yields
+ * the HTTP shape (switching away from a custom-embed base); without one, a
+ * custom-embed base passes through untouched: dimensions and keys mean
+ * nothing to a user-supplied function.
+ */
+declare function resolveEmbeddingConfig(provider: EmbeddingProvider | ResolvedEmbeddingProvider | undefined, override: Partial<EmbeddingConfig> | undefined): ResolvedEmbeddingProvider | undefined;
+type EmbeddingCallResult = {
+    vectors: number[][];
+    /** The provider-reported `model` field, when present. */
+    servedModel?: string;
+    dimensions: number;
+    tokens?: {
+        input: number;
+    };
+    /** Present when this call fetched fresh vectors; absent on full cache hits. */
+    latencyMs?: number;
+};
+/**
+ * Create a run-scoped embedding client: one shared vector cache so a
+ * reference reused across checks is embedded once, plus the retry/backoff
+ * policy for a single request. The cache key carries every setting that
+ * selects a different vector space (model, endpoint, requested dimensions);
+ * vectors from different configs must never mix in one comparison.
+ * In-flight fetches are deduplicated too: checks run concurrently, and two
+ * checks embedding the same reference must share one request, not race past
+ * each other into two.
+ */
+declare function createEmbeddingClient(): EmbeddingClient;
+/**
+ * Cosine similarity of two vectors, L2-normalizing first: identical result
+ * on already-normalized providers (OpenAI), correct on unnormalized ones
+ * (raw sentence-transformers served via OpenAI-compatible gateways). A
+ * zero-magnitude vector has no direction: similarity 0, per the guard every
+ * surveyed framework ships.
+ */
+declare function cosineSimilarity(a: readonly number[], b: readonly number[]): number;
+/** The run-scoped embedding client surface, for threading through contexts. */
+type EmbeddingClient = {
+    embed: (texts: string[], provider: ResolvedEmbeddingProvider) => Promise<EmbeddingCallResult>;
+};
+/**
+ * The recorded settings signature: everything that can move the number.
+ * `apo-v1` is the grading-semantics version (model + returned dims + cosine
+ * on L2-normalized vectors + newline-collapsed inputs); bump it if
+ * preprocessing or the metric ever change, so old signatures stay honest.
+ */
+declare function embeddingSettingsSignature(model: string, dimensions: number): string;
+
 /**
  * The outcome of a single assertion.
  *
@@ -843,8 +1073,14 @@ type AssertionResult = {
      */
     received?: unknown;
     location?: CheckLocation;
-    evaluator_type?: "llm" | "code" | "agent";
+    evaluator_type?: "llm" | "code" | "agent" | "embedding";
     judge?: JudgeMetadata;
+    /**
+     * Details about the embedding-similarity call that graded this assertion
+     * (`t.semantic`): model, settings signature, similarity, threshold,
+     * latency. Absent for every other evaluator.
+     */
+    embedding?: EmbeddingMetadata;
 };
 /**
  * Result of evaluating a single check.
@@ -886,13 +1122,18 @@ type EvaluationItemResult = {
      * - ``"regex"`` — pattern matching
      * Older persisted results may still use ``"llm"`` at this level.
      */
-    evaluator_type?: "llm" | "code" | "agent" | "regex" | "mixed";
+    evaluator_type?: "llm" | "code" | "agent" | "regex" | "embedding" | "mixed";
     /**
      * If this check was judged by an LLM, details about the judge call
      * (model, prompt, response, tokens, cost, latency). Populated by the
      * evaluator author; absent for code-only evaluators.
      */
     judge?: JudgeMetadata;
+    /**
+     * If this check was graded by embedding similarity (`t.semantic`), the
+     * pinned settings + score details. Absent otherwise.
+     */
+    embedding?: EmbeddingMetadata;
     /**
      * For code checks: the source location of the failure (parsed from the
      * thrown error / failed assertion stack). Lets the dashboard highlight the
@@ -1315,6 +1556,37 @@ type TokenBudgetOptions = {
     turn?: number;
     kind?: TokenKind;
 };
+/**
+ * Which retrieved document a retrieval assertion looks for. A string is a
+ * document id, matched exactly or as the parent of a chunk id (`"handbook"`
+ * matches `"handbook#p3"`). `idPrefix` covers other chunk-id schemes;
+ * `contentIncludes` covers retrievers that report no ids.
+ */
+type DocumentMatcher = string | {
+    id: string;
+} | {
+    idPrefix: string;
+} | {
+    contentIncludes: string;
+};
+type RetrievedOptions = {
+    /** The match must rank within a retrieval's first `topK` documents (retriever order). */
+    topK?: number;
+    /** Only retrievals whose query contains this text count. */
+    query?: string;
+};
+type GroundedOptions = {
+    /**
+     * What the answer must be grounded in. `"trace"` (the default) is every
+     * document this run retrieved; an array is author-supplied source texts.
+     */
+    sources?: "trace" | readonly string[];
+    label?: string;
+    /** Per-call judge config override, merged like `t.judge`'s. */
+    judge?: Partial<JudgeConfig>;
+    /** Ground-truth verdict, like `t.judge`'s: `"fail"` asserts the judge catches a known hallucination. */
+    expect?: "pass" | "fail";
+};
 /**
  * LLM judge model config for `t.judge(...)` calls in checks.ts. Threaded
  * through `runTask({ judge })` from the caller — the runner has no opinion
@@ -1368,6 +1640,17 @@ type JudgeScope = {
     /** Deliverable keys read so far, recorded by the check runner. */
     readDeliverableNames?: () => string[];
 };
+/**
+ * The embedding plane threaded into check contexts: the layered provider
+ * config, a run-scoped client (one shared vector cache, so a reference
+ * reused across checks is embedded once), and the tracer slice for the EMBEDDING
+ * observation + score record. Built once per run by the check runner.
+ */
+type EmbeddingRuntime = {
+    provider?: ResolvedEmbeddingProvider;
+    client: EmbeddingClient;
+    tracer?: EmbeddingTracer;
+};
 interface TestContext {
     /** Asserts a matching tool was called. Pass `{ count }` for an exact count. */
     calledTool(name: NameMatcher, opts?: ToolCallOptions): void;
@@ -1381,6 +1664,14 @@ interface TestContext {
     maxToolCalls(n: number): void;
     /** Asserts no tool/subagent call reported an error — anti-flail. */
     noFailedActions(): void;
+    /**
+     * Asserts a retrieval returned a matching document, optionally within its
+     * first `topK` and only for retrievals whose query matches. Recall as a
+     * test: one committed expectation per assertion, no score.
+     */
+    retrieved(document: DocumentMatcher, opts?: RetrievedOptions): void;
+    /** Asserts at most `n` retrievals ran (anti-flail). */
+    maxRetrievals(n: number): void;
     /** Asserts a skill was loaded. */
     loadedSkill(skill: string): void;
     /** Asserts a subagent delegation happened. */
@@ -1400,6 +1691,13 @@ interface TestContext {
     minTokens(n: number, opts?: TokenBudgetOptions): void;
     /** Escape hatch for a named predicate over the complete normalized run. */
     assert(label: string, predicate: (flow: TraceView) => boolean): void;
+    /**
+     * Negated presence assertions: `t.not.retrieved("acme-payroll")` passes
+     * when that document was not retrieved. Missing evidence stays
+     * `unsupported`, never a pass. Judged checks are not negatable; they carry
+     * their own polarity through `expect: "fail"`.
+     */
+    readonly not: NotTestContext;
     /**
      * Asserts steer n was delivered AND consumed: at least one generation
      * observation started after the steer's delivery timestamp. Fails closed —
@@ -1457,6 +1755,32 @@ interface TestContext {
          */
         expect?: "pass" | "fail";
     }): Promise<void>;
+    /**
+     * Semantic similarity: embeds `value` and `reference` with the configured
+     * embedding model (any OpenAI-compatible `/embeddings` endpoint:
+     * OpenRouter, OpenAI, local Ollama/vLLM/LM Studio) and records one
+     * assertion that passes when their cosine similarity ≥ `threshold`. The
+     * call is async, so the check function must `await` it. Deterministic under a pinned config,
+     * unlike `t.judge`. A non-string `value` is stringified like `t.check` matchers
+     * do; `reference` is the authored text to compare against.
+     *
+     * The threshold is required and has no default: cosine scales are
+     * model-bound (0.3 and 0.79 are both "paraphrase" on different models).
+     * Calibrate with a handful of labeled pass/fail pairs before committing to
+     * one. Every verdict records the raw score to 4 decimals and a settings
+     * signature (`model:1536d:cosine:apo-v1`); similarity numbers from
+     * different signatures are not comparable.
+     *
+     * ``opts.embedding`` overrides the run's embedding config **for this call
+     * only**, merging field-by-field like ``t.judge``'s config override.
+     */
+    semantic(value: unknown, reference: string, opts: {
+        /** Pass when cosine(value, reference) ≥ threshold. No default. */
+        threshold: number;
+        label?: string;
+        /** Per-call embedding config override, merged onto the threaded config. */
+        embedding?: Partial<EmbeddingConfig>;
+    }): Promise<void>;
     /**
      * Agentic judge: a tool-using LLM session that investigates the run's own
      * evidence (deliverables via `read_deliverable`/`search_deliverable`, the
@@ -1476,20 +1800,33 @@ interface TestContext {
      * the check passes only when its verdict matches.
      */
     agent(instruction: string, opts?: AgentJudgeOptions): Promise<void>;
+    /**
+     * Groundedness (faithfulness): an LLM judge checks that every factual claim
+     * in `value` is supported by the sources, by default the documents this run
+     * actually retrieved. A fixed rubric over `t.judge`, so `expect`, judge
+     * overrides and the second judge apply. Without retrieval evidence the
+     * outcome is `unsupported`, never a verdict on missing sources. Async: the
+     * check function must `await` it.
+     */
+    grounded(value: unknown, opts?: GroundedOptions): Promise<void>;
 }
+/**
+ * The assertions `t.not` negates: presence claims, whose opposite is a clear
+ * absence claim. Budgets and the existing negations (`notCalledTool`,
+ * `usedNoTools`) already state their opposite directly.
+ */
+type NotTestContext = Pick<TestContext, "calledTool" | "toolOrder" | "loadedSkill" | "calledSubagent" | "messageIncludes" | "retrieved" | "check">;
 /**
  * Canonical names of every assertion method on {@link TestContext}.
  *
- * Single source of truth for "what is a ``t.<method>`` call?" — consumers that
- * highlight, lint, or otherwise detect `t.*` usage in check source read this
- * array instead of keeping their own copy (which historically drifted out of
- * sync with the interface, leaving methods like ``t.maxTurns`` unstyled).
- *
- * The literal below is compile-time-checked against ``keyof TestContext``:
- * adding a method to the interface without registering it here is a type
- * error, and vice versa. See ``tests/test-context-methods.test.ts``.
+ * The dashboard keeps its own copy of this list for syntax highlighting,
+ * pinned to this array by an equality test, so the two cannot drift apart
+ * silently. The literal below is compile-time-checked against
+ * ``keyof TestContext``: adding a method to the interface without
+ * registering it here is a type error, and vice versa. See
+ * ``tests/test-context-methods.test.ts``.
  */
-declare const TEST_METHOD_NAMES: readonly ["calledTool", "notCalledTool", "toolOrder", "usedNoTools", "maxToolCalls", "noFailedActions", "loadedSkill", "calledSubagent", "messageIncludes", "maxTurns", "maxDurationMs", "maxTokens", "minTokens", "steerDelivered", "afterSteer", "assert", "check", "judge", "agent"];
+declare const TEST_METHOD_NAMES: readonly ["calledTool", "notCalledTool", "toolOrder", "usedNoTools", "maxToolCalls", "noFailedActions", "retrieved", "maxRetrievals", "loadedSkill", "calledSubagent", "messageIncludes", "maxTurns", "maxDurationMs", "maxTokens", "minTokens", "steerDelivered", "afterSteer", "assert", "not", "check", "judge", "semantic", "agent", "grounded"];
 
 type TaskDefinition<TAdapterName extends string = string, TDeliverable extends string = string> = {
     id: string;
@@ -1506,6 +1843,14 @@ type TaskDefinition<TAdapterName extends string = string, TDeliverable extends s
      * `prompt` that tells the judge what it is grading.
      */
     judge?: Partial<JudgeConfig>;
+    /**
+     * Task-level embedding layer: overrides the run-level
+     * `runTask({ embedding })` config for `t.semantic` calls in this task and
+     * is itself overridden per call (`t.semantic(..., { embedding })`). Set
+     * `{ model }` to grade this task's texts with a different embedding model
+     * than the suite default.
+     */
+    embedding?: Partial<EmbeddingConfig>;
     /**
      * Task-level judge-tools layer: MCP evidence servers for `t.agent` sessions
      * in this task. Overrides `runTask({ judgeTools })`, is overridden per
@@ -2070,6 +2415,13 @@ type RunTaskOptions = {
     tracing?: AgentTaskTraceOptions;
     /** LLM judge model config for `t.judge(...)` calls in the task checks. */
     judge?: JudgeConfig;
+    /**
+     * Embedding provider for `t.semantic(...)` calls: the HTTP config for any
+     * OpenAI-compatible `/embeddings` endpoint, or a custom `embed` function.
+     * Layered under `TaskDefinition.embedding` and per-call
+     * `t.semantic(..., { embedding })`.
+     */
+    embedding?: EmbeddingProvider;
     /**
      * Judge tool config for `t.agent(...)` sessions (MCP evidence servers).
      * Layered under `TaskDefinition.judgeTools` and per-call `tools.mcp`.
@@ -2215,6 +2567,7 @@ declare function discoverAgentTaskDirs(rootDir: string): string[];
 type AgentTaskRuntime = {
     judge?: JudgeConfig;
     judgeTools?: JudgeToolsConfig;
+    embedding?: EmbeddingProvider;
 };
 type AgentTaskRunSummary = {
     taskDir: string;
@@ -2321,6 +2674,7 @@ interface OTelSpanProcessorLifecycle {
 declare class ApoSpanProcessor implements OTelSpanProcessorLifecycle {
     private spanMap;
     private servedModelByParent;
+    private servingByParent;
     onStart(span: OTelSpan, _parentContext: OTelContext): void;
     onEnd(span: OTelReadableSpan): void;
     forceFlush(): Promise<void>;
@@ -2700,4 +3054,4 @@ type TranscriptCaptureResult = {
 };
 declare function replayAdapterTranscript(capture: AdapterTranscriptCapture, options: ReplayAdapterTranscriptOptions): Promise<TranscriptCaptureResult>;
 
-export { type AISDKResult, type AdapterDefinition, type AdapterRuntimeState, type AdapterSession, type AdapterTranscriptCapture, type AgentBudget, type AgentEvidence, type AgentJudgeOptions, type AgentJudgeOutcome, type AgentJudgeSession, type AgentJudgeStep, type AgentProgressEvent, type AgentTaskCliOptions, type AgentTaskRunConfiguration, AgentTaskRunError, type AgentTaskRunSummary, type AgentTaskRuntime, AgentTaskTraceContext, AgentTaskTraceOptions, type AgentTurnResult, type AnthropicMessage, type ApoRunContext, ApoSpanProcessor, type ArtifactUploadConfig, COMPUTE_MAX_DEPTH, COMPUTE_MAX_EXPR, type CheckCompaction, type CheckContext, type CheckGroup, type CleanupContext, type CollectDeliverablesContext, type CollectedDeliverables, type ComputeResult, type DeliverableDefinition, type DeliverableSummary, type DeliverableValidationResult, type DescribeRegistration, type DurationBudgetOptions, type EvidenceFingerprint, type ExportOtlpTracesOptions, type FileArtifact, type FileArtifactOptions, type FileEntry, type Flow, type FlowEvent, FlowView, type InitializeContext, JUDGE_SEGMENT_LIMIT, type JudgeConfig, type JudgeContext, type JudgePromptBuilder, type JudgeScope, type JudgeToolsConfig, type LoadedTask, type ManifestFile, type ManifestFileInput, type Matcher, type McpHttpTransport, type McpServerConfig, type McpStdioTransport, type ModeClass, NO_CHECKS_REGISTERED_MESSAGE, type NameMatcher, type OpenAIMessage, type OtlpAttribute, type OtlpAttributeValue, type OtlpSpan, type OtlpTracesPayload, type ParsedTranscriptSession, type PreparedTaskResult, RECEIVED_VALUE_LIMIT, type RegisterApoTracingOptions, type RejudgeCheckStability, type RejudgeEndpoints, RejudgeError, type RejudgeOptions, type RejudgeOutcome, type ReplayAdapterTranscriptOptions, type RunTaskOptions, type SecondJudgeFacts, type SecondJudgeFactsInput, type StartSessionContext, type SteerContext, type SteerDeliveryBoundary, type SteerRecord, type SteerResult, type SteerSpec, type SteerTrigger, TEST_METHOD_NAMES, type TaskConfig, type TaskDefinition, type TaskEvaluationResult, TaskFiles, type TaskRevisionManifestV1, type TaskRunResult, type TaskScope, type TaskTranscript, type TaskTranscriptTurn, type TestContext, type TestRegistration, type TokenBudgetOptions, type ToolCallOptions, type ToolCallStatus, type TranscriptCaptureResult, TranscriptReplayError, type TranscriptReplayOptions, type TranscriptSource, type TranscriptToolCall, type TranscriptTurn, type TranscriptUsage, type TurnContext, type TurnFn, type TurnRecord, type TypedAdapterDefinition, type ValueMatcher, buildApoAuthHeaders, buildManifest, canonicalManifestJson, compactChecksForSubmission, connectMcpServers, contentSha256, defineAdapter, defineTask, describe, detectTranscriptSource, discoverAgentTaskDirs, equals, evaluateComputeExpression, expandSecretPlaceholders, exportOtlpTraces, fileArtifact, filePaths, fromAISDK, fromAnthropicMessages, fromOpenAIMessages, getActiveApoRun, getTaskSteers, getTaskTurn, includes, isFileArtifact, loadTask, loadTaskRuntime, matchValue, matches, normalizeManifestPath, parseAgentTaskCliArgs, parseClaudeCodeTranscript, parseCodexTranscript, persistFileArtifacts, registerApoTracing, rejudgeTaskRun, replayAdapterTranscript, resetApoTracing, resetFlowChecks, resetTaskRegistry, resetTaskSteers, resetTaskTurn, resolveMcpServerPaths, resolveOtlpTracesUrl, resolveTurn, runAgentTaskCli, runTask, runTaskDir, satisfies, secondJudgeFacts, secondJudgeTakeaway, sha256Hex, similarity, steer, task, defineCheck as test, transcriptSessionToOtlp, turn, withApoRun, withApoRunSync };
+export { type AISDKResult, type AdapterDefinition, type AdapterRuntimeState, type AdapterSession, type AdapterTranscriptCapture, type AgentBudget, type AgentEvidence, type AgentJudgeOptions, type AgentJudgeOutcome, type AgentJudgeSession, type AgentJudgeStep, type AgentProgressEvent, type AgentTaskCliOptions, type AgentTaskRunConfiguration, AgentTaskRunError, type AgentTaskRunSummary, type AgentTaskRuntime, AgentTaskTraceContext, AgentTaskTraceOptions, type AgentTurnResult, type AnthropicMessage, type ApoRunContext, ApoSpanProcessor, type ArtifactUploadConfig, COMPUTE_MAX_DEPTH, COMPUTE_MAX_EXPR, type CheckCompaction, type CheckContext, type CheckGroup, type CleanupContext, type CollectDeliverablesContext, type CollectedDeliverables, type ComputeResult, type DeliverableDefinition, type DeliverableSummary, type DeliverableValidationResult, type DescribeRegistration, type DocumentMatcher, type DurationBudgetOptions, type EmbeddingCallResult, type EmbeddingClient, type EmbeddingConfig, type EmbeddingMetadata, type EmbeddingProvider, type EmbeddingRuntime, type EvidenceFingerprint, type ExportOtlpTracesOptions, type FileArtifact, type FileArtifactOptions, type FileEntry, type Flow, type FlowEvent, FlowView, type GroundedOptions, type InitializeContext, JUDGE_SEGMENT_LIMIT, type JudgeConfig, type JudgeContext, type JudgePromptBuilder, type JudgeScope, type JudgeToolsConfig, type LoadedTask, type ManifestFile, type ManifestFileInput, type Matcher, type McpHttpTransport, type McpServerConfig, type McpStdioTransport, type ModeClass, NO_CHECKS_REGISTERED_MESSAGE, type NameMatcher, type NotTestContext, type OpenAIMessage, type OtlpAttribute, type OtlpAttributeValue, type OtlpSpan, type OtlpTracesPayload, type ParsedTranscriptSession, type PreparedTaskResult, RECEIVED_VALUE_LIMIT, type RegisterApoTracingOptions, type RejudgeCheckStability, type RejudgeEndpoints, RejudgeError, type RejudgeOptions, type RejudgeOutcome, type ReplayAdapterTranscriptOptions, type ResolvedEmbeddingProvider, type RetrievedOptions, type RunTaskOptions, type SecondJudgeFacts, type SecondJudgeFactsInput, type StartSessionContext, type SteerContext, type SteerDeliveryBoundary, type SteerRecord, type SteerResult, type SteerSpec, type SteerTrigger, TEST_METHOD_NAMES, type TaskConfig, type TaskDefinition, type TaskEvaluationResult, TaskFiles, type TaskRevisionManifestV1, type TaskRunResult, type TaskScope, type TaskTranscript, type TaskTranscriptTurn, type TestContext, type TestRegistration, type TokenBudgetOptions, type ToolCallOptions, type ToolCallStatus, type TranscriptCaptureResult, TranscriptReplayError, type TranscriptReplayOptions, type TranscriptSource, type TranscriptToolCall, type TranscriptTurn, type TranscriptUsage, type TurnContext, type TurnFn, type TurnRecord, type TypedAdapterDefinition, type ValueMatcher, buildApoAuthHeaders, buildManifest, canonicalManifestJson, compactChecksForSubmission, connectMcpServers, contentSha256, cosineSimilarity, createEmbeddingClient, defineAdapter, defineTask, describe, detectTranscriptSource, discoverAgentTaskDirs, embeddingSettingsSignature, equals, evaluateComputeExpression, expandSecretPlaceholders, exportOtlpTraces, fileArtifact, filePaths, fromAISDK, fromAnthropicMessages, fromOpenAIMessages, getActiveApoRun, getTaskSteers, getTaskTurn, includes, isFileArtifact, loadTask, loadTaskRuntime, matchValue, matches, normalizeManifestPath, parseAgentTaskCliArgs, parseClaudeCodeTranscript, parseCodexTranscript, persistFileArtifacts, registerApoTracing, rejudgeTaskRun, replayAdapterTranscript, resetApoTracing, resetFlowChecks, resetTaskRegistry, resetTaskSteers, resetTaskTurn, resolveEmbeddingConfig, resolveMcpServerPaths, resolveOtlpTracesUrl, resolveTurn, runAgentTaskCli, runTask, runTaskDir, satisfies, secondJudgeFacts, secondJudgeTakeaway, sha256Hex, similarity, steer, task, defineCheck as test, transcriptSessionToOtlp, turn, withApoRun, withApoRunSync };