@apo-ai/sdk 0.5.0 → 0.7.0

package/README.md

@@ -1,14 +1,18 @@
 # apo SDK
 
-TypeScript/JavaScript SDK for the [apo](.) backend — an agent testing and
-observability platform. The SDK has three entry points:
+TypeScript/JavaScript SDK for [apo](https://github.com/samikuikka/apo), the
+testing and engineering system that turns expert knowledge into executable
+capability specifications for agent harnesses. The task API runs a real harness
+against that definition of done; the tracing API preserves the evidence a human
+or coding agent needs to improve it. The SDK's entry points:
 
-- **`@apo-ai/sdk`** — config + error types shared across the surface.
 - **`@apo-ai/sdk/otel`** — OpenTelemetry-native tracing. Wrap your LLM calls and
   agent steps so they land in apo as structured spans, then attach scores.
-- **`@apo-ai/sdk/agent-task`** — the agent-task evaluation framework. Define tasks,
-  adapters, and checks; run them against an agent and collect structured
-  results.
+- **`@apo-ai/sdk/agent-task`** — the primary capability-testing surface. Define
+  tasks, adapters, and tests; run them against the real harness and collect a
+  verdict with structured evidence.
+- **`@apo-ai/sdk/agent-task/integrations/{ai-sdk,openai,anthropic}`** —
+  per-framework tracing wrappers re-exported for direct import.
 
 ## Installation
 
@@ -36,57 +40,23 @@ no long-lived npm token is stored in the repository.
 
 ## Configuration
 
-`readConfig()` reads backend/project/credentials from environment variables.
-
-| Field       | Env var (server)            | Env var (Next.js, browser-safe)      | Required |
-|-------------|-----------------------------|--------------------------------------|----------|
-| `endpoint`  | `APO_BACKEND_URL`           | `NEXT_PUBLIC_APO_BACKEND_URL`        | yes      |
-| `project`   | `APO_PROJECT`               | `NEXT_PUBLIC_APO_PROJECT`            | yes      |
-| `publicKey` | `APO_PUBLIC_KEY`            | — *(server-side only — see below)*   | two-key  |
-| `secretKey` | `APO_SECRET_KEY`            | —                                    | two-key  |
-| `apiKey`    | `APO_API_KEY`               | —                                    | legacy   |
-
-The Next.js (`NEXT_PUBLIC_*`) variants are read first, then the plain server
-variants. `apiKey` is the legacy single-key format (`sk-…`); prefer the
-two-key model (`publicKey` + `secretKey`, generated as `pk-apo-…` / `sk-apo-…`
-in the dashboard).
-
-there is no browser-safe variant of `APO_PUBLIC_KEY`. The public
-identifier alone does not authorize ingestion, and exposing it in a
-browser bundle creates a misleading direct-browser integration.
-`NEXT_PUBLIC_APO_PUBLIC_KEY` is intentionally not read. Telemetry
-submission always requires both halves of an API-key pair sent as HTTP
-Basic (`base64("pk-apo-…:sk-apo-…")`); the SDK never synthesizes partial
-Basic credentials from only one half.
+The tracing surface (`@apo-ai/sdk/otel`) reads credentials from environment
+variables when they are not passed explicitly:
 
-```ts
-import { readConfig, type EnvConfig } from "@apo-ai/sdk";
-
-const config: EnvConfig = readConfig();
-```
-
-## API reference — `@apo-ai/sdk`
-
-The root entry is intentionally thin: shared types + config + errors. The
-actual tracing surface lives at `@apo-ai/sdk/otel`.
-
-### Types
-
-The trace/observation parameter types used by the OTel helpers:
-`CreateTraceParams`, `CreateSpanParams`, `EndSpanParams`, `TraceRunContext`,
-`TraceRunOptions`, `TraceStepOptions`, `TraceEventOptions`, `IngestionEvent`,
-`CreateScoreParams`, `ClientOptions`, `ParameterOverrides`, `ObserveOptions`,
-`ObservationContext`.
-
-### `readConfig(): EnvConfig`
-
-Read endpoint/project/keys from environment variables (table above).
-
-### Errors
+| Purpose                  | Env var             | Used for                                   |
+|--------------------------|---------------------|--------------------------------------------|
+| OTLP traces endpoint     | `APO_OTLP_ENDPOINT` | Where spans are exported                   |
+| Project (diagnostic)     | `APO_PROJECT`       | Resource attribute only — auth owns tenancy |
+| Two-key auth (Basic)     | `APO_PUBLIC_KEY` + `APO_SECRET_KEY` | `Authorization: Basic base64(pk:sk)` |
+| Bearer token             | `APO_AUTH_TOKEN`    | Short-lived task-run tokens; used only when the key pair is absent |
 
-`ClientError` (Effect `Data.TaggedError`), `ConfigurationError`,
-`ClientErrorCode`. `ClientError` carries a `code` field for categorising
-failures.
+Telemetry submission always requires both halves of an API-key pair sent as
+HTTP Basic (`base64("pk-apo-…:sk-apo-…")`); the SDK never synthesizes partial
+Basic credentials from only one half. There is deliberately no
+`NEXT_PUBLIC_*` browser variant — a public identifier alone does not
+authorize ingestion, and exposing it in a browser bundle creates a misleading
+direct-browser integration. Use `buildApoAuthHeaders` (exported from
+`@apo-ai/sdk/otel`) to build the headers explicitly.
 
 ## Tracing — `@apo-ai/sdk/otel`
 
@@ -115,7 +85,7 @@ call this if your app already configures OTel itself).
 ```ts
 const handle = await configureApoTelemetry({
   takeOwnership: true,
-  endpoint: process.env.APO_OTLP_ENDPOINT ?? "http://localhost:8000/v1/otlp",
+  endpoint: process.env.APO_OTLP_ENDPOINT ?? "http://localhost:8000/api/public/otel/v1/traces",
   // headers, resource attributes, batch/simple processor, etc.
 });
 
@@ -199,12 +169,10 @@ import {
 - **`test(id, fn)`** — register a test through the scope returned by `task()`.
   The callback receives `t` (flat, eve-style assertions over the run's flow)
   and the task-selected deliverables, inferred from the adapter.
-- **`runTask(task, adapter, options?)`** — execute a single task and return a
-  `TaskRunResult` (transcript + evaluation).
+- **`runTask(taskDir, options?)`** — execute a task and return a
+  `TaskRunResult` (transcript + evaluation). The adapter comes from the task
+  definition.
 - **`loadTask(dir)` / `discoverAgentTaskDirs()`** — load tasks from disk.
-- **`createAgentTaskTraceClient(config)`** — the adapter-side trace client
-  passed into runs; the auth token is supplied by the backend runner via
-  `APO_AUTH_TOKEN`.
 
 ### Testing (`*.eval.ts`)
 
@@ -277,8 +245,8 @@ anything). Matchers: `includes(substring|RegExp)`, `equals(value)` (deep),
 `satisfies(predicate, label)`, `similarity(expected, threshold = 0.8)` (fuzzy,
 normalized Levenshtein).
 
-For apo tasks the flow is built automatically from the run's trace (via
-`createFlowTee`) — no extra wiring.
+For apo tasks the flow is built automatically from the run's trace
+projection — no extra wiring.
 
 **`t.judge(value, instruction)` — LLM-backed assertions.** Configure the judge
 with `runTask(dir, { judge: { model, apiKey?, baseURL? } })`, or set
@@ -297,21 +265,22 @@ never revealed. The SDK appends its JSON response contract to any custom
 `system` constant per task and vary only `user` to preserve the cached prompt
 prefix across a task's criteria (issue #161).
 
-**Testing agents not built on apo's adapter.** Build a `Flow` from the
-framework's own output with a normalizer, then run the same checks:
+**Agents not built on apo's adapter.** `fromOpenAIMessages(messages)`,
+`fromAnthropicMessages(messages)`, and `fromAISDK(result)` convert another
+framework's output into the neutral `Flow` format so it can be inspected with
+`FlowView`:
 
 ```ts
-import { runFlowChecks, test } from "@apo-ai/sdk/agent-task";
-import { fromAISDK } from "@apo-ai/sdk/agent-task";        // or fromOpenAIMessages / fromAnthropicMessages
+import { fromAISDK, FlowView } from "@apo-ai/sdk/agent-task";
 
-const flow = fromAISDK(myGenerateTextResult);          // their framework → Flow
-test("used-tools", (t) => { t.calledTool("read_file"); });
-const results = await runFlowChecks({ flow, deliverables: { reply: myGenerateTextResult.text } });
+const view = new FlowView(fromAISDK(myGenerateTextResult));
+view.toolNamesInOrder; // e.g. ["read_file", "search_content"]
+view.reply;            // last assistant message text
 ```
 
-`fromOpenAIMessages(messages)`, `fromAnthropicMessages(messages)`, and
-`fromAISDK(result)` each convert one source into the neutral `Flow` the checks
-read — the plugs that make the testing framework reusable across agent stacks.
+These normalizers are **deprecated** compatibility adapters — the canonical
+path emits standard OTel spans (see the tracing integrations above), which
+apo projects into the same view without a Flow intermediary.
 
 ### CLI / runtime
 

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

@@ -1,4 +1,4 @@
-import { A as AgentTaskTraceContext } from '../../tracing-D5Yhzq8e.js';
+import { A as AgentTaskTraceContext } from '../../tracing-DVLUqD-i.js';
 
 /**
  * Vercel AI SDK tracing integration for apo.
@@ -6,9 +6,9 @@ import { A as AgentTaskTraceContext } from '../../tracing-D5Yhzq8e.js';
  * Pass the result of {@link createApoTracer} to `generateText`'s
  * `experimental_telemetry` option. The AI SDK already emits OpenTelemetry
  * spans natively (e.g. `ai.toolCall`, `ai.generateText`); this tracer
- * intercepts them and translates them into apo trace spans. The FlowTee
- * picks up TOOL/GENERATION observations and builds the Flow that
- * `t.calledTool`, `t.noFailedActions`, and `t.messageIncludes` read.
+ * intercepts them and translates them into apo trace spans, where they
+ * become the TOOL/GENERATION observations that `t.calledTool`,
+ * `t.noFailedActions`, and `t.messageIncludes` read.
  *
  * The adapter author writes zero manual span code.
  *
@@ -109,8 +109,8 @@ interface CreateApoTracerOptions {
  * - `ai.generateText` → a GENERATION span (so `t.messageIncludes(text)` works)
  *   and error status → `t.noFailedActions()` catches it
  *
- * Other spans (`ai.generateText.doGenerate`, etc.) are ignored — the FlowTee
- * only cares about TOOL/AGENT/GENERATION observation types.
+ * Other spans (`ai.generateText.doGenerate`, etc.) are ignored — only
+ * TOOL/AGENT/GENERATION observation types are visible to `t.*` assertions.
  */
 declare function createApoTracer(options: CreateApoTracerOptions): {
     isEnabled: true;

package/dist/agent-task/integrations/ai-sdk.js

@@ -2,7 +2,7 @@
 // Do not edit by hand — edit the src/ originals and rebuild.
 import {
   createApoTracer
-} from "../../chunk-HKLBPIB4.js";
+} from "../../chunk-QHRWPVPZ.js";
 import "../../chunk-HWZVL6TS.js";
 export {
   createApoTracer

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

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

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

@@ -1,4 +1,4 @@
-import { A as AgentTaskTraceContext } from '../../tracing-D5Yhzq8e.js';
+import { A as AgentTaskTraceContext } from '../../tracing-DVLUqD-i.js';
 
 /**
  * OpenAI JS SDK tracing integration for apo.
@@ -8,8 +8,8 @@ import { A as AgentTaskTraceContext } from '../../tracing-D5Yhzq8e.js';
  * any manual span code in the adapter.
  *
  * Uses a Proxy to intercept the `create` method, then emits GENERATION +
- * TOOL spans through the trace context. The FlowTee picks these up and
- * builds the Flow that `t.calledTool` reads.
+ * TOOL spans through the trace context, where they become the observations
+ * that `t.calledTool` reads.
  *
  * @example
  * ```ts

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

@@ -2,7 +2,7 @@
 // Do not edit by hand — edit the src/ originals and rebuild.
 import {
   createApoOpenAI
-} from "../../chunk-DT2LMB7O.js";
+} from "../../chunk-6ZRW5IW6.js";
 import "../../chunk-GDB6SDGN.js";
 export {
   createApoOpenAI

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

@@ -1,4 +1,4 @@
-import { A as AgentTaskTraceContext, a as AgentTaskTraceOptions } from '../tracing-D5Yhzq8e.js';
+import { A as AgentTaskTraceContext, a as AgentTaskTraceOptions } from '../tracing-DVLUqD-i.js';
 export { CreateApoTracerOptions, createApoTracer } from './integrations/ai-sdk.js';
 export { CreateApoOpenAIOptions, createApoOpenAI } from './integrations/openai.js';
 export { CreateApoAnthropicOptions, createApoAnthropic } from './integrations/anthropic.js';
@@ -323,6 +323,13 @@ type AssertionOutcome = "pass" | "fail" | "unsupported";
 type JudgeMetadata = {
     /** Model identifier, e.g. ``"google/gemini-2.5-flash-lite"``. */
     model?: string;
+    /**
+     * Which response contract elicited this judgment (#163): reasoning-first
+     * (the default) or the legacy verdict-first (``pass`` before
+     * ``reasoning``, via ``APO_JUDGE_VERDICT_FIRST``). Group comparisons
+     * across the default flip on this field, not on time.
+     */
+    contract?: "verdict-first" | "reasoning-first";
     /** The messages sent to the judge LLM. */
     prompt?: {
         system?: string;
@@ -343,6 +350,102 @@ type JudgeMetadata = {
     latency_ms?: number;
     /** Temperature or other sampling parameters, if relevant. */
     temperature?: number;
+    /**
+     * Agentic-judge session transcript (`t.agent`). Absent for single-shot
+     * `t.judge` calls. Records every investigation step (tool calls with
+     * truncated results), the session outcome, per-step usage, and the
+     * content-hashed evidence manifest (replay audit backbone).
+     */
+    session?: AgentJudgeSession;
+    /**
+     * Second-grader evidence: a typed-decision model (Jev via OpenRouter's
+     * `/alpha/decisions`) graded the same deliverable + instruction alongside
+     * the primary judge. Opt-in via `APO_SECOND_JUDGE_MODEL`. The primary
+     * verdict is never changed by it — the point is agreement and confidence
+     * as extra signals per check, not a second vote.
+     */
+    secondJudge?: SecondJudgeEvidence;
+};
+/**
+ * Evidence from the second grader. `error` is set when the decisions
+ * endpoint could not be reached — a failed second opinion must never
+ * affect the check's verdict.
+ */
+type SecondJudgeEvidence = {
+    /** Decision-model id that graded, e.g. `typesafe/jev-1.13`. */
+    model: string;
+    /** The typed verdict the model returned. */
+    choice?: "pass" | "fail";
+    /** P(pass) from the model's probability distribution over the choice. */
+    passProbability?: number;
+    /** The model's own confidence in its choice (0-1). */
+    confidence?: number;
+    /** Input tokens billed for the decision, when the provider reports usage. */
+    inputTokens?: number;
+    /** Cost in USD, when the provider reports it. */
+    costUsd?: number;
+    /** Wall-clock latency of the decision call in milliseconds. */
+    latencyMs?: number;
+    /** Why no verdict was recorded (transport/HTTP/parse failure). */
+    error?: string;
+};
+/**
+ * One investigation step of an agentic judge session. Tool results are
+ * truncated text; the sha256 + byte size are always kept so the full value
+ * stays recoverable from the evidence store (the transcript is an index,
+ * not a copy).
+ */
+type AgentJudgeStep = {
+    index: number;
+    tool_calls?: {
+        name: string;
+        input?: string;
+        result?: string;
+        result_sha256?: string;
+        result_bytes?: number;
+    }[];
+    /** Assistant prose, if the model produced text alongside tool calls. */
+    text?: string;
+    tokens?: {
+        input?: number;
+        output?: number;
+        cost?: number;
+    };
+    latency_ms?: number;
+};
+/** How an agentic judge session ended. */
+type AgentJudgeOutcome = "verdict" | "budget_exhausted" | "error";
+/**
+ * A fingerprint of one piece of evidence the judge consumed — the
+ * content-addressed manifest. Never truncated.
+ */
+type EvidenceFingerprint = {
+    step: number;
+    tool: string;
+    args_sha256?: string;
+    result_sha256: string;
+    result_bytes: number;
+};
+/** Transcript-shaped record of one `t.agent` session. */
+type AgentJudgeSession = {
+    /** Tool names offered to the judge. */
+    tools?: string[];
+    /** Turn-0 context: system briefing and the rubric (user message). */
+    briefing?: {
+        system?: string;
+        rubric?: string;
+    };
+    /** Ordered investigation steps. */
+    steps?: AgentJudgeStep[];
+    outcome: AgentJudgeOutcome;
+    /** Evidence manifest — what this session consumed, hashed. Never truncated. */
+    evidence?: EvidenceFingerprint[];
+    usage?: {
+        steps?: number;
+        input_tokens?: number;
+        output_tokens?: number;
+        cache_read_tokens?: number;
+    };
 };
 /**
  * A source location for a failed code check — lets the dashboard render the
@@ -386,7 +489,7 @@ type AssertionResult = {
      */
     received?: unknown;
     location?: CheckLocation;
-    evaluator_type?: "llm" | "code";
+    evaluator_type?: "llm" | "code" | "agent";
     judge?: JudgeMetadata;
 };
 /**
@@ -416,7 +519,7 @@ type EvaluationItemResult = {
      * - ``"regex"`` — pattern matching
      * Older persisted results may still use ``"llm"`` at this level.
      */
-    evaluator_type?: "llm" | "code" | "regex";
+    evaluator_type?: "llm" | "code" | "agent" | "regex";
     /**
      * If this check was judged by an LLM, details about the judge call
      * (model, prompt, response, tokens, cost, latency). Populated by the
@@ -443,10 +546,10 @@ type EvaluationItemResult = {
      */
     assertions?: AssertionResult[];
     /**
-     * the snapshot source the checks ran against. Set to
-     * ``"legacy-flow"`` by the deprecated {@link runFlowChecks} wrapper so
-     * consumers can detect they're on the compatibility path. Absent on
-     * projection-first results (the default).
+     * the snapshot source the checks ran against. ``"local"`` marks locally
+     * recorded snapshots; ``"legacy-flow"`` survives only on results recorded
+     * by the removed Flow-path loader. Absent on projection-first results
+     * (the default).
      */
     source?: "canonical" | "local" | "legacy-flow";
     /**
@@ -557,6 +660,101 @@ type JudgePromptBuilder = (ctx: JudgeContext) => {
     user?: string;
 };
 
+/** One prior attempt of this task, as frozen at evaluation start. */
+type FrozenRunSummary = {
+    id: string;
+    status: string;
+    passed: boolean | null;
+    started_at?: string;
+    primary_model?: string | null;
+    passed_checks?: number | null;
+    failed_checks?: number | null;
+    corrected_tests?: unknown[];
+    /** True when this entry IS the run under judgment. */
+    is_run_under_judgment?: boolean;
+};
+/** A prior run's full check report (merged view, like the run detail page). */
+type HistoryRunDetail = {
+    id: string;
+    status: string;
+    checks: {
+        id: string;
+        pass: boolean;
+        evaluator: string;
+        reasoning?: string;
+        assertions?: {
+            pass: boolean;
+            expected?: string;
+            received?: string;
+        }[];
+    }[];
+    /** Human corrections recorded against this run; "none" when empty. */
+    human_corrections: unknown[] | "none";
+};
+/** The frozen evidence plane handed to every `t.agent` session. */
+type AgentHistoryPlane = {
+    /** Prior attempts of this task, frozen at evaluation start. */
+    runs: FrozenRunSummary[];
+    /**
+     * Fetch one prior run's merged check report. The run-under-judgment id
+     * returns an honest "you are deciding this run" answer instead of data
+     * whose checks are still being evaluated.
+     */
+    getRun(runId: string): Promise<HistoryRunDetail | {
+        error: string;
+    }>;
+    /** The backend's id for the run under judgment, when known. */
+    selfRunId?: string;
+};
+
+/**
+ * The agentic judge — `t.agent`. A tool-using LLM session that investigates
+ * the run's own evidence (deliverables, trace) before verdicting, powered by
+ * a lazy-loaded Vercel AI SDK engine. The judge semantics live here at the
+ * call site; the loop itself is engine-level: forced tool choice plus a
+ * done-tool verdict means the only exits are a verdict or the budget — every
+ * other ending is recorded as a failure with an explanation.
+ *
+ * Sessions are stateless per check: no memory crosses sessions (upstream
+ * ablations showed remembered judgments cascade errors). Everything the
+ * session consumed is recorded as a content-hashed manifest
+ * ({@link EvidenceFingerprint}) — the transcript is an index, not a copy.
+ */
+
+/** Hard ceilings for one agentic session. Every field overrides a default. */
+type AgentBudget = {
+    /** Max LLM turns (steps). Default 12. */
+    maxTurns?: number;
+    /** Max total tool executions. Default 24. */
+    maxToolCalls?: number;
+    /** Wall-clock ceiling. Default 300_000 ms. */
+    timeoutMs?: number;
+    /** Max cumulative bytes served by read/search tools. Default 2 MiB. */
+    maxReadBytes?: number;
+};
+/** Options for `t.agent(instruction, opts)`. */
+type AgentJudgeOptions = {
+    /** Pre-staged values rendered into turn 0, like `t.judge` values. */
+    exhibits?: unknown | unknown[];
+    /** Judge config override for this call only (merges field-by-field). */
+    judge?: Partial<JudgeConfig>;
+    /** Tool families; deliverables are always on. `trace: false` drops get_trace. */
+    tools?: {
+        trace?: boolean;
+    };
+    budget?: AgentBudget;
+    label?: string;
+};
+/** The local evidence plane a session can investigate. */
+type AgentEvidence = {
+    /** The run's deliverables, by name. */
+    deliverables: Record<string, unknown>;
+    /** The frozen trace projection; absent = no trace evidence plane. */
+    view?: TraceView;
+    /** This task's prior runs; absent = history plane unavailable. */
+    history?: AgentHistoryPlane;
+};
+
 /**
  * The assertion surface — `t`. Flat and eve-style: reads the trace (via
  * {@link TraceView}) for behavioural checks and grades explicit values via
@@ -652,6 +850,21 @@ interface TestContext {
         label?: string;
         judge?: Partial<JudgeConfig>;
     }): Promise<void>;
+    /**
+     * Agentic judge: a tool-using LLM session that investigates the run's own
+     * evidence (deliverables via `read_deliverable`/`search_deliverable`, the
+     * trace via `get_trace`) before verdicting with `finish_verdict`. Async —
+     * the check function must `await` it. Records a single assertion tagged
+     * ``evaluator_type: "agent"`` with the full session transcript attached.
+     *
+     * Unlike `t.judge`, the author states a rubric and the judge gathers its
+     * own evidence; `opts.exhibits` optionally pre-stages values into turn 0.
+     * The session is budgeted (defaults: 12 turns / 24 tool calls / 300 s /
+     * 2 MiB read) and fail-closed: a session that ends without a verdict is a
+     * recorded failure, never a silent pass. Costs more and runs minutes, not
+     * seconds — reserve it for rubrics that need investigation.
+     */
+    agent(instruction: string, opts?: AgentJudgeOptions): Promise<void>;
 }
 /**
  * Canonical names of every assertion method on {@link TestContext}.
@@ -665,7 +878,7 @@ interface 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", "assert", "check", "judge"];
+declare const TEST_METHOD_NAMES: readonly ["calledTool", "notCalledTool", "toolOrder", "usedNoTools", "maxToolCalls", "noFailedActions", "loadedSkill", "calledSubagent", "messageIncludes", "maxTurns", "maxDurationMs", "assert", "check", "judge", "agent"];
 
 type TaskDefinition<TAdapterName extends string = string, TDeliverable extends string = string> = {
     id: string;
@@ -927,6 +1140,40 @@ interface PreparedTaskResult {
  */
 declare function persistFileArtifacts(deliverables: Record<string, unknown>, config: ArtifactUploadConfig): Promise<PreparedTaskResult>;
 
+/**
+ * Check submission compaction (issue #175).
+ *
+ * The backend's ``check_report_storage.normalize_check_report`` truncates
+ * every ``received`` over 4 KiB and every judge prompt/response segment over
+ * 16 KiB into a marker before storing anything — the full value never
+ * survives server-side. This module applies the same limits at the producer,
+ * so a task judging N criteria against one large document sends N tiny
+ * markers instead of N copies of the document (a 43 MB result body becomes
+ * single-digit MB). Local rendering keeps the uncompacted values.
+ *
+ * The markers are byte-compatible with the backend's (same field names,
+ * preview length, and hash subject), so server-side normalization passes
+ * them through unchanged and old servers store them as-is.
+ */
+
+/** Mirrors backend RECEIVED_VALUE_LIMIT (check_report_storage.py). */
+declare const RECEIVED_VALUE_LIMIT: number;
+/** Mirrors backend JUDGE_SEGMENT_LIMIT. */
+declare const JUDGE_SEGMENT_LIMIT: number;
+interface CheckCompaction {
+    /** Copy of ``checks`` with oversized fields replaced by markers. */
+    checks: EvaluationItemResult[];
+    /** How many ``received`` values were replaced. */
+    truncatedValues: number;
+    /** How many judge prompt/response segments were replaced. */
+    truncatedSegments: number;
+}
+/**
+ * Return a submission-safe copy of ``checks``. Touched paths are copied;
+ * untouched values are shared. Input is never mutated.
+ */
+declare function compactChecksForSubmission(checks: readonly EvaluationItemResult[]): CheckCompaction;
+
 /**
  * Flow — the canonical, source-agnostic recording of "what happened" during
  * an agent run. This is the single substrate the testing framework reads.
@@ -1018,8 +1265,7 @@ declare class FlowView {
  * not the primary testing architecture. The canonical path is now the Trace
  * Projection snapshot (`TraceProjectionSnapshot` → `TraceView` →
  * `runTraceChecks`). These normalizers remain available during the
- * deprecation period; `snapshotFromFlow` bridges their output into the
- * projection contract. New integrations should emit standard OTel spans
+ * deprecation period. New integrations should emit standard OTel spans
  * instead of producing a Flow.
  */
 
@@ -1241,7 +1487,7 @@ type DeliverableValidationResult = {
  *
  * The processor is global, but run isolation is maintained via
  * {@link AsyncLocalStorage}: {@link getActiveApoRun} returns the current
- * run's trace context, so each span is routed to the correct run's FlowTee.
+ * run's trace context, so each span is routed to the correct run's trace.
  *
  * **Design: eager creation, deferred completion.** The apo span is created
  * at `onStart` (when initial attributes like tool name and model are
@@ -1465,4 +1711,4 @@ declare function canonicalManifestJson(manifest: TaskRevisionManifestV1): string
 /** SHA-256 (lowercase hex) of the canonical manifest JSON's UTF-8 bytes. */
 declare function contentSha256(manifest: TaskRevisionManifestV1): string;
 
-export { type AISDKResult, type AdapterDefinition, type AdapterRuntimeState, type AdapterSession, type AgentTaskCliOptions, type AgentTaskRunConfiguration, AgentTaskRunError, type AgentTaskRunSummary, type AgentTaskRuntime, AgentTaskTraceContext, AgentTaskTraceOptions, type AgentTurnResult, type AnthropicMessage, type ApoRunContext, ApoSpanProcessor, type ArtifactUploadConfig, type CheckContext, type CheckGroup, type CleanupContext, type CollectDeliverablesContext, type CollectedDeliverables, type DeliverableDefinition, type DeliverableSummary, type DeliverableValidationResult, type DescribeRegistration, type FileArtifact, type FileArtifactOptions, type FileEntry, type Flow, type FlowEvent, FlowView, type InitializeContext, type JudgeConfig, type JudgeContext, type JudgePromptBuilder, type JudgeScope, type LoadedTask, type ManifestFile, type ManifestFileInput, type Matcher, type ModeClass, type NameMatcher, type OpenAIMessage, type PreparedTaskResult, type RegisterApoTracingOptions, type RejudgeCheckStability, type RejudgeEndpoints, RejudgeError, type RejudgeOptions, type RejudgeOutcome, type RunTaskOptions, type StartSessionContext, 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 ToolCallOptions, type ToolCallStatus, type TurnContext, type TurnFn, type TurnRecord, type TypedAdapterDefinition, type ValueMatcher, buildManifest, canonicalManifestJson, contentSha256, defineAdapter, defineTask, describe, discoverAgentTaskDirs, equals, fileArtifact, filePaths, fromAISDK, fromAnthropicMessages, fromOpenAIMessages, getActiveApoRun, getTaskTurn, includes, isFileArtifact, loadTask, loadTaskRuntime, matchValue, matches, normalizeManifestPath, parseAgentTaskCliArgs, persistFileArtifacts, registerApoTracing, rejudgeTaskRun, resetApoTracing, resetFlowChecks, resetTaskRegistry, resetTaskTurn, resolveTurn, runAgentTaskCli, runTask, runTaskDir, satisfies, sha256Hex, similarity, task, defineCheck as test, turn, withApoRun, withApoRunSync };
+export { type AISDKResult, type AdapterDefinition, type AdapterRuntimeState, type AdapterSession, type AgentBudget, type AgentEvidence, type AgentJudgeOptions, type AgentJudgeOutcome, type AgentJudgeSession, type AgentJudgeStep, type AgentTaskCliOptions, type AgentTaskRunConfiguration, AgentTaskRunError, type AgentTaskRunSummary, type AgentTaskRuntime, AgentTaskTraceContext, AgentTaskTraceOptions, type AgentTurnResult, type AnthropicMessage, type ApoRunContext, ApoSpanProcessor, type ArtifactUploadConfig, type CheckCompaction, type CheckContext, type CheckGroup, type CleanupContext, type CollectDeliverablesContext, type CollectedDeliverables, type DeliverableDefinition, type DeliverableSummary, type DeliverableValidationResult, type DescribeRegistration, type EvidenceFingerprint, 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 LoadedTask, type ManifestFile, type ManifestFileInput, type Matcher, type ModeClass, type NameMatcher, type OpenAIMessage, type PreparedTaskResult, RECEIVED_VALUE_LIMIT, type RegisterApoTracingOptions, type RejudgeCheckStability, type RejudgeEndpoints, RejudgeError, type RejudgeOptions, type RejudgeOutcome, type RunTaskOptions, type StartSessionContext, 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 ToolCallOptions, type ToolCallStatus, type TurnContext, type TurnFn, type TurnRecord, type TypedAdapterDefinition, type ValueMatcher, buildManifest, canonicalManifestJson, compactChecksForSubmission, contentSha256, defineAdapter, defineTask, describe, discoverAgentTaskDirs, equals, fileArtifact, filePaths, fromAISDK, fromAnthropicMessages, fromOpenAIMessages, getActiveApoRun, getTaskTurn, includes, isFileArtifact, loadTask, loadTaskRuntime, matchValue, matches, normalizeManifestPath, parseAgentTaskCliArgs, persistFileArtifacts, registerApoTracing, rejudgeTaskRun, resetApoTracing, resetFlowChecks, resetTaskRegistry, resetTaskTurn, resolveTurn, runAgentTaskCli, runTask, runTaskDir, satisfies, sha256Hex, similarity, task, defineCheck as test, turn, withApoRun, withApoRunSync };