@apo-ai/sdk 0.2.0

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

@@ -0,0 +1,1326 @@
+import { A as AgentTaskTraceContext, a as AgentTaskTraceOptions } from '../tracing-DtbhYQV6.js';
+export { CreateApoTracerOptions, createApoTracer } from './integrations/ai-sdk.js';
+export { CreateApoOpenAIOptions, createApoOpenAI } from './integrations/openai.js';
+export { CreateApoAnthropicOptions, createApoAnthropic } from './integrations/anthropic.js';
+import '../types-C-nrDEVf.js';
+
+type TaskDefinition<TAdapterName extends string = string, TDeliverable extends string = string> = {
+    id: string;
+    adapter: TAdapterName;
+    description?: string;
+    deliverables: TDeliverable[];
+    maxTurns?: number;
+    metadata?: Record<string, unknown>;
+    checks?: string | false;
+};
+type TaskConfig<TDeliverable extends string = string> = Omit<TaskDefinition<string, TDeliverable>, "adapter">;
+type FileEntry = {
+    relativePath: string;
+    absolutePath: string;
+};
+
+declare class TaskFiles {
+    private entries;
+    constructor(entries: FileEntry[]);
+    read(relativePath: string): Promise<string>;
+    readBuffer(relativePath: string): Promise<Buffer>;
+    find(relativePath: string): FileEntry | undefined;
+    list(): FileEntry[];
+    has(relativePath: string): boolean;
+}
+
+type TurnRecord = {
+    turnNumber: number;
+    input: unknown;
+    output: unknown;
+};
+type TurnContext = {
+    files: TaskFiles;
+    transcript: TurnRecord[];
+};
+type TurnFn<TUserTurn = unknown> = (ctx: TurnContext) => Promise<TUserTurn | null> | TUserTurn | null;
+declare function turn<TUserTurn>(fn: TurnFn<TUserTurn>): void;
+declare function getTaskTurn(): TurnFn | undefined;
+declare function resetTaskTurn(): void;
+declare function resolveTurn(adapterTurn: TurnFn | undefined, taskTurn: TurnFn | undefined): TurnFn;
+
+type ValidatableSchemaLike = {
+    safeParse: (data: unknown) => {
+        success: boolean;
+        error?: {
+            message: string;
+        };
+    };
+};
+type DeliverableDefinition = ValidatableSchemaLike | {
+    schema?: ValidatableSchemaLike;
+} | null;
+type CollectedDeliverables = Record<string, unknown>;
+type AgentTurnResult = {
+    response: unknown;
+};
+/**
+ * The adapter-reported identity of the agent under test for one Task Run
+ *. The adapter resolves its configuration (env vars, aliases,
+ * defaults), constructs the agent from that same resolved object, and reports
+ * the resolved values here.
+ *
+ * - `model` is the exact identifier the adapter passed to its runtime.
+ * - `effort` is the exact short value that runtime used (`low`/`medium`/...
+ *   or `"default"`). Omitted means "the adapter did not report effort".
+ *
+ * The whole configuration is absent (`undefined`) when the adapter does not
+ * support reporting it. Values are descriptive — they never affect task
+ * selection, execution, scoring, retry, or deduplication.
+ */
+interface AgentTaskRunConfiguration {
+    model: string;
+    effort?: string;
+}
+type AdapterRuntimeState = Record<string, unknown>;
+type InitializeContext = {
+    task: TaskDefinition;
+    taskDir: string;
+    files: FileEntry[];
+    trace: AgentTaskTraceContext;
+};
+type StartSessionContext = {
+    task: TaskDefinition;
+    taskDir: string;
+    files: FileEntry[];
+    state?: AdapterRuntimeState;
+    trace: AgentTaskTraceContext;
+};
+type CollectDeliverablesContext = {
+    task: TaskDefinition;
+    taskDir: string;
+    files: FileEntry[];
+    state?: AdapterRuntimeState;
+    session: AdapterSession;
+    trace: AgentTaskTraceContext;
+};
+type CleanupContext = {
+    task: TaskDefinition;
+    taskDir: string;
+    files: FileEntry[];
+    state?: AdapterRuntimeState;
+    session?: AdapterSession;
+    trace: AgentTaskTraceContext;
+};
+type AdapterSession = {
+    /**
+     * The adapter's resolved model/effort for this run. Read by
+     * `runTask()` immediately after `startSession()` returns, validated, and
+     * copied into {@link TaskRunResult.runConfiguration}. Absent for adapters
+     * that do not report configuration.
+     */
+    runConfiguration?: AgentTaskRunConfiguration;
+    sendUserTurn: (turn: unknown, context: {
+        trace: AgentTaskTraceContext;
+        turnNumber: number;
+        parentSpanId?: string;
+    }) => Promise<AgentTurnResult>;
+    close?: () => Promise<void>;
+};
+type AdapterDefinition = {
+    name: string;
+    deliverables: Record<string, DeliverableDefinition>;
+    turn?: TurnFn;
+    initialize?: (ctx: InitializeContext) => Promise<AdapterRuntimeState | void>;
+    startSession: (ctx: StartSessionContext) => Promise<AdapterSession>;
+    collectDeliverables: (ctx: CollectDeliverablesContext) => Promise<CollectedDeliverables>;
+    cleanup?: (ctx: CleanupContext) => Promise<void>;
+};
+type TypedAdapterDefinition<TName extends string, TDeliverables extends Record<string, DeliverableDefinition>, TCollected extends CollectedDeliverables = CollectedDeliverables> = Omit<AdapterDefinition, "name" | "deliverables" | "collectDeliverables"> & {
+    name: TName;
+    deliverables: TDeliverables;
+    collectDeliverables: (ctx: CollectDeliverablesContext) => Promise<TCollected>;
+};
+
+/**
+ * Trace Projection snapshot contract.
+ *
+ * This is the immutable transport/read snapshot of a Trace Projection — the
+ * query-optimized representation shared by the dashboard and agent-task
+ * assertions. It is NOT a new domain entity and never a source of truth; the
+ * canonical OpenTelemetry spans remain authoritative.
+ *
+ * Both the Python backend and the TypeScript SDK MUST serialize to this exact
+ * lower-camel-case JSON contract, so assertions read the same shape whether
+ * the snapshot came from the canonical repository, a local/offline recorder,
+ * or a legacy-Flow compatibility adapter.
+ *
+ * Rules:
+ * - `schemaVersion` versions the JSON contract.
+ * - `projectionVersion` identifies the normalizer/projector interpretation.
+ * - `source` is diagnostic; only `"canonical"` represents a durably projected
+ *   Trace.
+ * - `complete` means the task execution root ended and every span in the
+ *   acknowledged export was projected. It does not promise no unrelated
+ *   service will ever export a late span.
+ * - Missing evidence is represented through `capabilities`, never converted to
+ *   empty arrays, zero duration, or successful status.
+ * - Observations are immutable and sorted deterministically by invocation
+ *   time, then span ID. Missing timestamps sort after timestamped ones.
+ */
+/** Whether a category of evidence is present in the projection. */
+type EvidenceAvailability = "available" | "partial" | "unavailable";
+/** Lifecycle status of an observation. `unset` = the source had no status. */
+type ObservationStatus = "unset" | "ok" | "error";
+/** What kind of Span an Observation was derived from. */
+type ObservationType = "SPAN" | "GENERATION" | "TOOL" | "AGENT" | "SKILL" | "CHAIN" | "RETRIEVER" | "EMBEDDING" | "GUARDRAIL";
+/**
+ * Per-category evidence availability. Every category must declare honestly
+ * what it carries so assertions can fail closed when evidence is missing
+ * instead of vacuously passing.
+ */
+interface TraceProjectionCapabilities {
+    messages: EvidenceAvailability;
+    tools: EvidenceAvailability;
+    errors: EvidenceAvailability;
+    timing: EvidenceAvailability;
+    skills: EvidenceAvailability;
+    subagents: EvidenceAvailability;
+}
+/** One chat message reconstructed from a generation observation. */
+interface TraceProjectionMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+}
+/**
+ * A derived interpretation of one Span, as shown by the dashboard and read by
+ * assertions. Unknown span kinds survive as `SPAN`; hierarchy is preserved via
+ * `parentSpanId`.
+ */
+interface TraceProjectionObservation {
+    spanId: string;
+    parentSpanId?: string;
+    type: ObservationType;
+    name: string;
+    startedAt?: string;
+    endedAt?: string;
+    durationMs?: number;
+    status: ObservationStatus;
+    errorMessage?: string;
+    input?: unknown;
+    output?: unknown;
+    model?: string;
+    toolName?: string;
+    toolParameters?: unknown;
+    toolResult?: unknown;
+    messages?: readonly TraceProjectionMessage[];
+    metadata?: Readonly<Record<string, unknown>>;
+}
+/** Trace-level facts. All timing is optional; absence is honest. */
+interface TraceProjectionTrace {
+    traceId: string;
+    taskRunId?: string;
+    name?: string;
+    startedAt?: string;
+    endedAt?: string;
+    durationMs?: number;
+    complete: boolean;
+}
+/**
+ * The immutable read snapshot. Identical JSON shape across canonical, local,
+ * and legacy-flow sources — only `source` and `capabilities` differ.
+ */
+interface TraceProjectionSnapshot {
+    schemaVersion: 1;
+    projectionVersion: number;
+    source: "canonical" | "local" | "legacy-flow";
+    trace: TraceProjectionTrace;
+    capabilities: TraceProjectionCapabilities;
+    observations: readonly TraceProjectionObservation[];
+}
+
+/**
+ * The outcome of a single assertion.
+ *
+ * - ``"pass"`` → ``pass=true``
+ * - ``"fail"`` → ``pass=false``
+ * - ``"unsupported"`` → ``pass=false``. The trace projection lacked the
+ *   evidence this assertion needed (e.g. timing, error status). An unsupported
+ *   trace assertion fails closed and explains which evidence was unavailable;
+ *   it must never silently pass. Value assertions (``t.check``) and LLM
+ *   assertions (``t.judge``) do not consult trace capabilities and retain
+ *   their existing pass/fail behavior.
+ */
+type AssertionOutcome = "pass" | "fail" | "unsupported";
+/**
+ * Metadata about an LLM judge call. Populated by evaluators that use an
+ * LLM to make their pass/fail decision. All fields optional so code-only
+ * evaluators can leave this undefined.
+ */
+type JudgeMetadata = {
+    /** Model identifier, e.g. ``"google/gemini-2.5-flash-lite"``. */
+    model?: string;
+    /** The messages sent to the judge LLM. */
+    prompt?: {
+        system?: string;
+        user?: string;
+    };
+    /** Raw LLM response text before parsing into {pass, reasoning}. */
+    response?: string;
+    /** Token usage if available from the provider. */
+    tokens?: {
+        input: number;
+        output: number;
+        cache_creation?: number;
+        cache_read?: number;
+    };
+    /** Estimated cost in USD, if available. */
+    cost?: number;
+    /** Wall-clock latency of the judge call in milliseconds. */
+    latency_ms?: number;
+    /** Temperature or other sampling parameters, if relevant. */
+    temperature?: number;
+};
+/**
+ * A source location for a failed code check — lets the dashboard render the
+ * failure inline, editor-style. ``file`` is a display name (e.g. the checks
+ * filename); ``line``/``column`` are 1-indexed into that file.
+ */
+type CheckLocation = {
+    file: string;
+    line: number;
+    column?: number;
+};
+/**
+ * A single assertion within a code check (the recorder collects many per
+ * check). Carries structured Expected/Received so the dashboard can render
+ * testing-framework-style failures instead of a flattened prose string.
+ *
+ * - ``expected`` — what the assertion wanted (matcher label, or "≥1 read_file
+ *   call" for trace asserts). Absent when not meaningful.
+ * - ``received`` — the actual value/count the run produced. Serialized scalar
+ *   for code assertions; the raw evaluated value for LLM judges (see field).
+ * - ``location`` — where in the checks source this assertion lives.
+ */
+type AssertionResult = {
+    id: string;
+    pass: boolean;
+    reasoning: string;
+    /**
+     * The outcome category. ``"unsupported"`` means the trace
+     * projection lacked the evidence this assertion needed (e.g. timing,
+     * errors) — it fails closed (``pass=false``) with an explanatory reason
+     * rather than vacuously passing. Absent on legacy results.
+     */
+    outcome?: AssertionOutcome;
+    expected?: string;
+    /**
+     * The actual value the assertion observed. For code assertions this is a
+     * short serialized scalar (`"3"`, `"read_file → write_file"`); for LLM
+     * judges it is the **raw value passed to `t.judge`** — an arbitrary JSON
+     * value (string, object, array, primitive), so the dashboard can render it
+     * with a structured viewer instead of a truncated string.
+     */
+    received?: unknown;
+    location?: CheckLocation;
+    evaluator_type?: "llm" | "code";
+    judge?: JudgeMetadata;
+};
+/**
+ * Result of evaluating a single check.
+ *
+ * The three required fields ({@link id}, {@link pass}, {@link reasoning})
+ * have been here since the beginning. The optional fields below are
+ * enriched metadata that lets the dashboard show *what* was evaluated,
+ * *how* it was evaluated, and — for LLM judges — exactly what the judge
+ * was asked and what it answered.
+ *
+ * Evaluators that don't populate the optional fields still work; the
+ * dashboard gracefully falls back to the legacy three-field display.
+ */
+type EvaluationItemResult = {
+    id: string;
+    pass: boolean;
+    reasoning: string;
+    /** The rubric instruction from the task definition ("PASS if …"). */
+    instruction?: string;
+    /** Name of the deliverable this check was evaluated against. */
+    deliverable?: string;
+    /**
+     * What kind of evaluator produced this result.
+     * Registered checks use ``"code"``. LLM-backed assertions inside a check
+     * carry ``evaluator_type: "llm"`` in {@link assertions}.
+     * - ``"regex"`` — pattern matching
+     * Older persisted results may still use ``"llm"`` at this level.
+     */
+    evaluator_type?: "llm" | "code" | "regex";
+    /**
+     * 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;
+    /**
+     * For code checks: the source location of the failure (parsed from the
+     * thrown error / failed assertion stack). Lets the dashboard highlight the
+     * failing line. Absent when not a code check, when the check passed, or
+     * when no frame could be resolved to the checks module.
+     */
+    location?: CheckLocation;
+    /**
+     * For code checks: the source filename the result came from (normally
+     * the ``*.eval.ts`` file; ``"checks.ts"`` for legacy tasks), so the dashboard can show it even
+     * when no line was resolved.
+     */
+    source_file?: string;
+    /**
+     * For code checks: the per-assertion breakdown (Expected/Received/location
+     * each). Lets the dashboard mark every failing assertion at its own line,
+     * testing-framework-style. Absent for non-code evaluators and old runs.
+     */
+    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).
+     */
+    source?: "canonical" | "local" | "legacy-flow";
+    /**
+     * the id of the `describe()` group this check was declared
+     * inside. Absent for checks declared at the top level (no enclosing
+     * describe) and for old results. The dashboard groups checks by this field.
+     */
+    group_id?: string;
+    /**
+     * the display name of the enclosing `describe()` group.
+     * Defaults to the group id when the group was declared without a name.
+     * Absent when {@link group_id} is absent.
+     */
+    group_name?: string;
+};
+type TaskEvaluationResult = {
+    checks: EvaluationItemResult[];
+    pass: boolean;
+};
+type TaskTranscript = {
+    turns: TaskTranscriptTurn[];
+};
+type TaskTranscriptTurn = {
+    turnNumber: number;
+    userAction: unknown;
+    agentResponse: unknown;
+};
+type TaskRunResult = {
+    task: TaskDefinition;
+    taskDir: string;
+    files: FileEntry[];
+    traceRunId?: string;
+    result: TaskEvaluationResult;
+    deliverables: Record<string, unknown>;
+    transcript: TaskTranscript;
+    /**
+     * The adapter's resolved model/effort for this run. Captured and
+     * normalized from `AdapterSession.runConfiguration` immediately after the
+     * session opens. Absent for adapters that do not report configuration.
+     */
+    runConfiguration?: AgentTaskRunConfiguration;
+};
+
+/**
+ * TraceView — typed, capability-gated, derived access over a
+ * {@link TraceProjectionSnapshot}. This is the read model the projection-first
+ * assertion surface queries. It is the projection analogue of `FlowView`.
+ *
+ * The defining difference from `FlowView` is **capability honesty**: when the
+ * snapshot declares a category of evidence `unavailable`, the derived numeric
+ * facts (`durationMs`, `failedActions`, `turnCount`) return `undefined` rather
+ * than zero — so an assertion like `t.maxDurationMs` can record an explicit
+ * `unsupported` outcome instead of vacuously passing against a fabricated 0ms.
+ *
+ * `toolNamesInOrder` sorts by observation invocation time (`startedAt`) with a
+ * deterministic span-ID tie-breaker — NOT array/completion order. This fixes
+ * the drift where concurrent tools appeared in completion order.
+ */
+
+/** A tool call derived from a `TOOL` observation. */
+interface TraceToolCall {
+    spanId: string;
+    name: string;
+    input?: unknown;
+    output?: unknown;
+    status: ObservationStatus;
+    startedAt?: string;
+}
+/** A skill load derived from a `SKILL` observation. */
+interface TraceSkillLoad {
+    spanId: string;
+    skill: string;
+    startedAt?: string;
+}
+/** A subagent delegation derived from an `AGENT` observation. */
+interface TraceSubagentCall {
+    spanId: string;
+    agent: string;
+    output?: unknown;
+    status: ObservationStatus;
+    startedAt?: string;
+}
+declare class TraceView {
+    readonly snapshot: TraceProjectionSnapshot;
+    constructor(snapshot: TraceProjectionSnapshot);
+    /** Evidence availability for a capability. */
+    requireCapability(capability: keyof TraceProjectionCapabilities): EvidenceAvailability;
+    /** Whether a capability is reported as available (not partial/unavailable). */
+    private isAvailable;
+    /** All chat messages flattened across generation observations, in order. */
+    get messages(): readonly TraceProjectionMessage[];
+    /** Tool calls derived from `TOOL` observations, in invocation order. */
+    get toolCalls(): readonly TraceToolCall[];
+    /** Tool names in invocation order with deterministic span-ID tie-breaking. */
+    get toolNamesInOrder(): readonly string[];
+    /** Skill loads derived from `SKILL` observations, in invocation order. */
+    get skillLoads(): readonly TraceSkillLoad[];
+    /** Subagent delegations derived from `AGENT` observations, in invocation order. */
+    get subagentCalls(): readonly TraceSubagentCall[];
+    /** Last assistant message content — the agent's "reply". Empty if none. */
+    get reply(): string;
+    /**
+     * Number of completed assistant turns, or `undefined` when message evidence
+     * is unavailable (capability honesty).
+     */
+    get turnCount(): number | undefined;
+    /**
+     * Number of tool/subagent observations that reported an error, or `undefined`
+     * when error evidence is unavailable (capability honesty).
+     */
+    get failedActions(): number | undefined;
+    /**
+     * Total execution duration in milliseconds, or `undefined` when timing
+     * evidence is unavailable (capability honesty). Uses trace-level
+     * startedAt/endedAt when present.
+     */
+    get durationMs(): number | undefined;
+    /**
+     * Observations sorted deterministically by invocation time then span ID.
+     * Memoized per TraceView instance since the snapshot is immutable.
+     */
+    private get sortedObservations();
+    private _sorted;
+}
+
+/**
+ * Value matchers for `t.check(value, matcher)`. Small, composable, and the
+ * single way to assert on deliverables/values (replaces the old `expect`).
+ *
+ * A matcher is just `{ label, test }` — easy to build custom ones inline with
+ * `satisfies(fn, label)`.
+ */
+type Matcher<T> = {
+    label: string;
+    test: (value: T) => boolean;
+};
+/** Coerces the value to a string and checks it contains a substring or RegExp. Gate. */
+declare function includes(needle: string | RegExp): Matcher<unknown>;
+/** Deep structural equality. Gate. */
+declare function equals<T>(expected: T): Matcher<T>;
+/**
+ * Validates against a Standard-Schema-shaped validator (Zod, Valibot, …) —
+ * anything exposing `safeParse`. Gate.
+ */
+declare function matches<T = unknown>(schema: {
+    safeParse: (value: unknown) => {
+        success: boolean;
+    };
+}): Matcher<T>;
+/** Custom boolean predicate. Gate. */
+declare function satisfies<T>(predicate: (value: T) => boolean, label: string): Matcher<T>;
+type ValueMatcher<T> = T | RegExp | ((value: T) => boolean);
+declare function matchValue<T>(actual: T, matcher: ValueMatcher<T>): boolean;
+/** Normalized Levenshtein similarity. Pass when score ≥ threshold (default 0.8). */
+declare function similarity(expected: string, threshold?: number): Matcher<unknown>;
+
+/**
+ * The assertion surface — `t`. Flat and eve-style: reads the trace (via
+ * {@link TraceView}) for behavioural checks and grades explicit values via
+ * `t.check`. Everything records (never throws), so a check reports all of its
+ * failures, not just the first.
+ *
+ * Every assertion records structured ``expected`` / ``received`` values so
+ * the dashboard can render testing-framework-style failures (Expected /
+ * Received) instead of only a prose message.
+ */
+
+/** A tool/agent name matcher: literal (exact), RegExp, or predicate. */
+type NameMatcher = string | RegExp | ((name: string) => boolean);
+/** Options for matching tool calls by count and recorded fields. */
+type ToolCallOptions = {
+    count?: number;
+    input?: ValueMatcher<unknown>;
+    output?: ValueMatcher<unknown>;
+    status?: "ok" | "error";
+};
+/**
+ * LLM judge model config for `t.judge(...)` calls in checks.ts. Threaded
+ * through `runTask({ judge })` from the caller — the runner has no opinion
+ * about which model grades a deliverable.
+ */
+type JudgeConfig = {
+    /** Model id, e.g. ``"google/gemini-2.5-flash-lite"``. */
+    model: string;
+    /** Override the OpenRouter/OpenAI-compatible base URL. */
+    baseURL?: string;
+    /** Override the API key (defaults to env). */
+    apiKey?: string;
+};
+interface TestContext {
+    /** Asserts a matching tool was called. Pass `{ count }` for an exact count. */
+    calledTool(name: NameMatcher, opts?: ToolCallOptions): void;
+    /** Asserts no tool call matches the supplied name and field constraints. */
+    notCalledTool(name: NameMatcher, opts?: Omit<ToolCallOptions, "count">): void;
+    /** Asserts the named tools appear, in this order (as a subsequence). */
+    toolOrder(names: string[]): void;
+    /** Asserts no tool calls happened at all. */
+    usedNoTools(): void;
+    /** Asserts at most `n` tool calls — anti-flail. */
+    maxToolCalls(n: number): void;
+    /** Asserts no tool/subagent call reported an error — anti-flail. */
+    noFailedActions(): void;
+    /** Asserts a skill was loaded. */
+    loadedSkill(skill: string): void;
+    /** Asserts a subagent delegation happened. */
+    calledSubagent(agent: string): void;
+    /** Asserts the agent's reply contains a substring or RegExp. */
+    messageIncludes(token: string | RegExp): void;
+    /** Asserts the run took at most `n` turns — anti-flail. */
+    maxTurns(n: number): void;
+    /** Asserts the run took at most `n` milliseconds — anti-flail. */
+    maxDurationMs(n: number): void;
+    /** Escape hatch for a named predicate over the complete normalized run. */
+    assert(label: string, predicate: (flow: TraceView) => boolean): void;
+    /** Grades any value (a deliverable, parsed JSON, anything) with a matcher. */
+    check<T>(value: T, matcher: Matcher<T>, label?: string): void;
+    /**
+     * LLM-as-judge: asks the configured judge model to grade ``value`` against
+     * ``instruction`` (a natural-language rubric). Async — the check function
+     * must `await` it. Records a single assertion tagged
+     * ``evaluator_type: "llm"`` with judge metadata (model, prompt, response,
+     * tokens, latency) attached.
+     *
+     * ``opts.judge`` overrides the run's judge config **for this call only**,
+     * merging field-by-field onto the config threaded in via ``runTask({ judge })``
+     * — set ``{ model }`` to escalate a finicky criterion to a stronger model
+     * without switching the whole run. Absent fields inherit from the base config.
+     */
+    judge(values: unknown | unknown[], instruction: string, opts?: {
+        label?: string;
+        judge?: Partial<JudgeConfig>;
+    }): Promise<void>;
+}
+/**
+ * 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``.
+ */
+declare const TEST_METHOD_NAMES: readonly ["calledTool", "notCalledTool", "toolOrder", "usedNoTools", "maxToolCalls", "noFailedActions", "loadedSkill", "calledSubagent", "messageIncludes", "maxTurns", "maxDurationMs", "assert", "check", "judge"];
+
+/**
+ * Check runner — builds a {@link TestContext} (`t`) per registered check from
+ * a {@link TraceProjectionSnapshot}, runs it, and aggregates every recorded
+ * assertion into one evaluation result per check.
+ */
+
+/**
+ * The check context — deliberately framework-agnostic. `deliverables` is the
+ * output; `files`/`task` are optional and untyped here so the core never
+ * depends on any agent-framework's types. apo passes its own typed values;
+ * other frameworks pass whatever they have (or omit).
+ *
+ * A task-scoped ``test`` gets typed deliverables from the adapter automatically:
+ *
+ * ```ts
+ * const { test } = task("review", {
+ *   adapter: reviewAdapter,
+ *   deliverables: ["result"],
+ * });
+ * test("id", (t, { deliverables }) => {
+ *   deliverables.result  // typed as ReviewResult
+ * });
+ * ```
+ *
+ * The generic overload of {@link defineCheck} remains available for
+ * framework-agnostic checks that have no task scope.
+ */
+type CheckContext<TDeliverables = Record<string, unknown>> = {
+    deliverables: TDeliverables;
+    files?: unknown;
+    task?: unknown;
+};
+declare function filePaths(files: unknown): string[];
+type CheckFn<TDeliverables = Record<string, unknown>> = (t: TestContext, ctx: CheckContext<TDeliverables>) => Promise<void> | void;
+type TestRegistration<TDeliverables = Record<string, unknown>> = (id: string, fn: CheckFn<TDeliverables>) => void;
+/**
+ * A registered `describe()` group — single-level, organizational only. See
+ * {@link describe}.
+ */
+type CheckGroup = {
+    /** Stable, unique group id (kebab-case). Grouping key + React key. */
+    id: string;
+    /** Human-readable label shown in the dashboard. Defaults to the id. */
+    name: string;
+};
+/** Signature of the `describe` registration primitive. */
+type DescribeRegistration = {
+    (id: string, fn: () => void): void;
+    (id: string, name: string, fn: () => void): void;
+};
+/** Register a check. The `fn` receives the assertion surface `t` and the output.
+ *
+ * Framework-agnostic callers can pass a deliverables type explicitly:
+ * ```ts
+ * type Deliverables = { result: ReviewResult; stats: Stats };
+ * defineCheck<Deliverables>("id", (t, { deliverables }) => { ... });
+ * ```
+ */
+declare function defineCheck<TDeliverables>(id: string, fn: CheckFn<TDeliverables>): void;
+declare function defineCheck(id: string, fn: CheckFn): void;
+declare function resetFlowChecks(): void;
+/**
+ * Register a single-level group of checks. Runs `fn` synchronously;
+ * any `test()`/`defineCheck()` call inside it is stamped with the group's id
+ * and display name, so the dashboard can nest those checks under a collapsible
+ * header with a roll-up verdict.
+ *
+ * Groups are **organizational only** — they do not change execution order,
+ * concurrency, or the task verdict. Nesting is prohibited: calling `describe`
+ * inside a `describe` callback throws. Use sibling groups under one task
+ * instead.
+ *
+ * The `id` is stable (survives display-name edits); `name` is the human label
+ * shown in the dashboard and defaults to `id` when omitted.
+ *
+ * ```ts
+ * const { test, describe } = task("bind", { adapter, deliverables });
+ * describe("rules", "Rules — each comment becomes a rule", () => {
+ *   RULE_GOLD.forEach((g) => test(`R-${g.id} — …`, async (t, { deliverables }) => { … }));
+ * });
+ * ```
+ */
+declare function describe(id: string, fn: () => void): void;
+declare function describe(id: string, name: string, fn: () => void): void;
+
+declare const TASK_ADAPTER_SYMBOL: unique symbol;
+declare function resetTaskRegistry(): void;
+type DefinedTask<TName extends string, TDeliverableDefs extends Record<string, DeliverableDefinition>> = TaskDefinition<TName, keyof TDeliverableDefs & string> & {
+    readonly [TASK_ADAPTER_SYMBOL]: TypedAdapterDefinition<TName, TDeliverableDefs>;
+};
+/** Legacy two-file task definition. New tasks should use {@link task}. */
+declare function defineTask<const TName extends string, const TDeliverableDefs extends Record<string, DeliverableDefinition>>(adapter: TypedAdapterDefinition<TName, TDeliverableDefs>, config: TaskConfig<keyof TDeliverableDefs & string>): DefinedTask<TName, TDeliverableDefs>;
+type TaskScope<TDeliverables> = {
+    test: TestRegistration<TDeliverables>;
+    /**
+     * Register a single-level group of checks. See
+     * {@link describe} in `checks/flow-runner.ts`. Returned from `task()` so the
+     * `test` inside the callback stays task-scoped (typed deliverables).
+     */
+    describe: DescribeRegistration;
+};
+/**
+ * Register a task + its checks in ONE file. The `name` is the task id;
+ * `config` includes the adapter, deliverables, and other metadata. Checks
+ * are registered through the returned, adapter-typed `test` function.
+ *
+ * ```ts
+ * const { test } = task("code-review", {
+ *   adapter: realAgentAdapter,
+ *   deliverables: ["result", "tool_log", "stats"],
+ *   maxTurns: 2,
+ * });
+ *
+ * test("reviewed-methodically", (t, { deliverables }) => {
+ *   t.check(deliverables.result, includes("finding"));
+ * });
+ *
+ * // A task that needs dev-machine resources (cloud creds, VPC, stage) can
+ * // declare execution: "local" so `apo task run` runs it on the caller's
+ * // machine while still recording a backend run row.
+ * task("bind-e2e", {
+ *   adapter: bindAdapter,
+ *   deliverables: ["summary"],
+ *   execution: "local",
+ * });
+ * ```
+ */
+declare function task<const TTaskId extends string, const TAdapterName extends string, const TDeliverableDefs extends Record<string, DeliverableDefinition>, TCollected extends CollectedDeliverables, const TSelected extends readonly (DeliverableKey<TCollected> & keyof TDeliverableDefs)[]>(name: TTaskId, config: Omit<TaskConfig<TSelected[number] & string>, "id" | "checks" | "deliverables"> & {
+    adapter: TypedAdapterDefinition<TAdapterName, TDeliverableDefs, TCollected>;
+    deliverables: TSelected;
+}): TaskScope<SelectedDeliverables<TCollected, TSelected>>;
+type DeliverableKey<TCollected> = TCollected extends unknown ? keyof TCollected & string : never;
+type DeliverableValue<TCollected, TKey extends PropertyKey> = TCollected extends unknown ? TKey extends keyof TCollected ? TCollected[TKey] : never : never;
+type SelectedDeliverables<TCollected, TSelected extends readonly PropertyKey[]> = {
+    [TKey in TSelected[number]]-?: Exclude<DeliverableValue<TCollected, TKey>, null | undefined>;
+};
+
+type LoadedTask = {
+    task: TaskDefinition;
+    adapter: AdapterDefinition;
+    taskDir: string;
+    files: FileEntry[];
+    /** Legacy external checks module, absent for single-file tasks. */
+    checksPath: string | null;
+    /** True when task(), test(), and turn() were registered by the eval file. */
+    inlineChecks: boolean;
+    /** The temp-module URL the task was imported from (used for location pinning). */
+    moduleUrl: string;
+    /** The original eval filename (e.g. "code-review.eval.ts") — used as source_file on check results. */
+    evalFileName: string;
+};
+declare function loadTask(taskDir: string): Promise<LoadedTask>;
+
+declare function defineAdapter<const TName extends string, const TDeliverables extends Record<string, DeliverableDefinition>, TCollected extends CollectedDeliverables>(adapter: TypedAdapterDefinition<TName, TDeliverables, TCollected>): TypedAdapterDefinition<TName, TDeliverables, TCollected>;
+
+/**
+ * file Artifact declaration helper.
+ *
+ * A ``FileArtifact`` is a path descriptor that identifies a regular local
+ * file at persistence time. The SDK streams it to the backend (two-phase
+ * upload) rather than buffering bytes in the result body.
+ *
+ * Rules:
+ * - ``path`` must identify a regular local file at persistence time;
+ * - directories, sockets, devices, and symbolic links are rejected;
+ * - the default display filename is ``basename(path)``;
+ * - the default media type is ``application/octet-stream``;
+ * - ``t.judge(fileArtifact(...))`` is rejected: a path descriptor is not file
+ *   content. Authors must explicitly read/parse the content to judge it.
+ */
+interface FileArtifact {
+    readonly kind: "apo.file-artifact";
+    readonly path: string;
+    readonly mediaType: string;
+    readonly displayFilename: string;
+}
+interface FileArtifactOptions {
+    readonly mediaType?: string;
+    readonly displayFilename?: string;
+}
+/**
+ * Declare a file Deliverable from a local file path.
+ *
+ * Validates eagerly that ``path`` points to an existing regular file (not a
+ * directory, symlink, socket, or device) so authors get an actionable error
+ * before the backend creates an upload intent.
+ */
+declare function fileArtifact(path: string, options?: FileArtifactOptions): FileArtifact;
+declare function isFileArtifact(value: unknown): value is FileArtifact;
+
+/**
+ * file Artifact uploader.
+ *
+ * After checks run against the original in-memory Deliverables, this module
+ * partitions JSON values from file Artifacts, streams each file to the
+ * backend's two-phase upload endpoint, and returns only JSON Deliverables for
+ * the final result body. File bytes never travel through the result request
+ * or subprocess stdout.
+ *
+ * Storage failure does not flip a failed test into a pass: it raises, so the
+ * caller records the run as errored.
+ */
+interface DeliverableSummary {
+    id: string;
+    name: string;
+    kind: "json" | "artifact";
+    status: "pending" | "ready" | "failed";
+    media_type: string;
+    display_filename: string | null;
+    size_bytes: number;
+    sha256: string;
+    download_url: string | null;
+}
+interface ArtifactUploadConfig {
+    /** The Task Run id owning these Deliverables. */
+    taskRunId: string;
+    /** Bearer token (service token or API key) authorizing the upload. */
+    authToken: string;
+    /** Backend base URL, e.g. ``http://127.0.0.1:8000``. */
+    baseUrl: string;
+    /** Injectable fetch (tests pass a stub); defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+interface PreparedTaskResult {
+    /** JSON-only deliverables safe to send in the final result body. */
+    jsonDeliverables: Record<string, unknown>;
+    /** Successfully uploaded file Artifacts (summaries only, no bodies). */
+    artifactUploads: DeliverableSummary[];
+}
+/**
+ * Partition and persist Deliverables after checks complete.
+ *
+ * - file Artifacts are streamed to the backend (hash, create intent, PUT);
+ * - JSON values are returned untouched for the result body;
+ * - the local path of any Artifact is never embedded in the result.
+ */
+declare function persistFileArtifacts(deliverables: Record<string, unknown>, config: ArtifactUploadConfig): Promise<PreparedTaskResult>;
+
+/**
+ * Flow — the canonical, source-agnostic recording of "what happened" during
+ * an agent run. This is the single substrate the testing framework reads.
+ *
+ * It is deliberately neutral: it does not know about our trace, the AI SDK,
+ * OpenAI, Anthropic, etc. Concrete sources are converted into a {@link Flow}
+ * by a normalizer (see `fromApoTrace`, etc.). The framework depends only on
+ * this interface — that is what hides the source complexity.
+ */
+type ToolCallStatus = "ok" | "error";
+type FlowEvent = {
+    kind: "message";
+    role: "user" | "assistant" | "system";
+    text: string;
+    ts?: number;
+} | {
+    kind: "tool_call";
+    name: string;
+    input?: unknown;
+    output?: unknown;
+    status?: ToolCallStatus;
+    latencyMs?: number;
+    ts?: number;
+} | {
+    kind: "skill_load";
+    skill: string;
+    ts?: number;
+} | {
+    kind: "subagent_call";
+    agent: string;
+    output?: unknown;
+    status?: ToolCallStatus;
+    latencyMs?: number;
+    ts?: number;
+};
+type Flow = {
+    /** Ordered events — the timeline of the run. */
+    events: readonly FlowEvent[];
+    /** Wall-clock start/end, when known. Sources without clocks may omit them. */
+    startedAt?: number;
+    endedAt?: number;
+};
+
+/**
+ * FlowView — typed, derived access over a {@link Flow}. This is the read model
+ * the assertion surface (`t`) queries. It hides all the filtering/derivation
+ * so assertions stay one-liners.
+ */
+
+type ToolCall = Extract<FlowEvent, {
+    kind: "tool_call";
+}>;
+type SkillLoad = Extract<FlowEvent, {
+    kind: "skill_load";
+}>;
+type SubagentCall = Extract<FlowEvent, {
+    kind: "subagent_call";
+}>;
+type Message = Extract<FlowEvent, {
+    kind: "message";
+}>;
+declare class FlowView {
+    readonly events: readonly FlowEvent[];
+    readonly startedAt?: number;
+    readonly endedAt?: number;
+    constructor(flow: Flow);
+    get messages(): Message[];
+    get toolCalls(): ToolCall[];
+    get skillLoads(): SkillLoad[];
+    get subagentCalls(): SubagentCall[];
+    get toolNamesInOrder(): string[];
+    /** Last assistant message text — the agent's "reply". */
+    get reply(): string;
+    /** Number of completed assistant turns. */
+    get turnCount(): number;
+    /** Tool or subagent calls that reported an error. */
+    get failedActions(): number;
+    get durationMs(): number;
+}
+
+/**
+ * Cross-framework Flow normalizers — the "plugs" that let agents NOT built on
+ * apo's adapter produce a {@link Flow} from their own output, so the same
+ * `t.*` checks work for everyone.
+ *
+ * Each normalizer is `(source) => Flow`. Add new ones by following the shape.
+ *
+ * @deprecated These are **compatibility recording adapters**,
+ * 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
+ * instead of producing a Flow.
+ */
+
+interface OpenAIMessage {
+    role?: string;
+    content?: string | null;
+    tool_calls?: Array<{
+        id?: string;
+        function?: {
+            name?: string;
+            arguments?: string;
+        };
+    }>;
+    tool_call_id?: string;
+}
+declare function fromOpenAIMessages(messages: OpenAIMessage[]): Flow;
+interface AnthropicMessage {
+    role?: string;
+    content?: Array<{
+        type: "text";
+        text: string;
+    } | {
+        type: "tool_use";
+        id: string;
+        name: string;
+        input?: unknown;
+    } | {
+        type: "tool_result";
+        tool_use_id: string;
+        content?: unknown;
+    }>;
+}
+declare function fromAnthropicMessages(messages: AnthropicMessage[]): Flow;
+interface AISDKResult {
+    steps?: Array<{
+        text?: string;
+        toolCalls?: Array<{
+            toolName: string;
+            input?: unknown;
+        }>;
+        toolResults?: Array<{
+            toolName: string;
+            output?: unknown;
+        }>;
+    }>;
+}
+declare function fromAISDK(result: AISDKResult): Flow;
+
+/**
+ * Error thrown when a Task Run fails after the adapter's Run Configuration
+ * has been resolved. Carries the resolved {@link AgentTaskRunConfiguration} so
+ * callers (e.g. the CLI error-report path) can forward model/effort to the
+ * backend even when the run never produced a summary (issue #40).
+ *
+ * The original failure is preserved on `cause`. Only errors thrown after
+ * `startSession` reported a *valid* configuration are wrapped — a
+ * configuration-validation failure propagates unwrapped (there is nothing to
+ * attach).
+ */
+declare class AgentTaskRunError extends Error {
+    readonly runConfiguration?: AgentTaskRunConfiguration;
+    /** The original error that caused the run to fail (preserved for diagnostics). */
+    readonly cause?: unknown;
+    constructor(message: string, options: {
+        runConfiguration?: AgentTaskRunConfiguration;
+        cause?: unknown;
+    });
+}
+type RunTaskOptions = {
+    maxTurnsOverride?: number;
+    tracing?: AgentTaskTraceOptions;
+    /** LLM judge model config for `t.judge(...)` calls in the task checks. */
+    judge?: JudgeConfig;
+    onTurn?: (turnNumber: number, userAction: TaskTranscriptTurn["userAction"], agentResponse: unknown) => void;
+    /**
+     * Skip the internal `loadTask(taskDir)` call and reuse an already-loaded
+     * task definition.
+     *
+     * The eval module's top level runs once per `loadTask` (it is copied to a
+     * temp file and imported with all registries reset), so loading twice per
+     * run breaks evals whose load-time behavior is not idempotent across module
+     * systems (e.g. a helper that re-exports CJS `require()`-cached registrations
+     * — the second import hits the cache and registers zero checks). Callers
+     * that already need a `LoadedTask` for their own purposes (`runTaskDir`,
+     * `runner-entry.ts`) should always pass it through here to keep the eval
+     * import count at exactly one per run.
+     *
+     * When omitted, `runTask` calls `loadTask(taskDir)` itself. The `taskDir`
+     * argument is still required for that fallback and is otherwise unused.
+     */
+    loaded?: LoadedTask;
+};
+declare function runTask(taskDir: string, options?: RunTaskOptions): Promise<TaskRunResult>;
+
+type AgentTaskCliOptions = {
+    task?: string;
+    dir?: string;
+    grep?: string;
+    help?: boolean;
+};
+declare function parseAgentTaskCliArgs(argv: string[]): AgentTaskCliOptions;
+declare function runAgentTaskCli(argv: string[], cwd?: string): Promise<number>;
+
+declare function discoverAgentTaskDirs(rootDir: string): string[];
+
+type AgentTaskRuntime = {
+    judge?: JudgeConfig;
+};
+type AgentTaskRunSummary = {
+    taskDir: string;
+    taskId: string;
+    pass: boolean;
+    checks: EvaluationItemResult[];
+    /** Adapter that ran the task. Forwarded to the backend when recording locally. */
+    adapterName?: string;
+    /** Trace id this run claimed (when tracing was enabled). */
+    traceRunId?: string;
+    /** Deliverables the adapter produced. */
+    deliverables?: Record<string, unknown>;
+    /** Per-turn transcript of the run. */
+    transcript?: Record<string, unknown>;
+    /** adapter-reported model/effort, forwarded when recording locally. */
+    runConfiguration?: AgentTaskRunConfiguration;
+};
+declare function loadTaskRuntime(_taskDir: string): Promise<AgentTaskRuntime>;
+declare function runTaskDir(taskDir: string): Promise<AgentTaskRunSummary>;
+
+type DeliverableValidationResult = {
+    results: EvaluationItemResult[];
+    brokenDeliverables: Record<string, string>;
+};
+
+/**
+ * ApoSpanProcessor — an OpenTelemetry SpanProcessor that routes GenAI spans
+ * into apo's Flow.
+ *
+ * This is the OTel-native tracing path. After calling {@link registerApoTracing},
+ * any SDK that emits OTel spans (Vercel AI SDK, OpenAI Agents SDK, etc.)
+ * will be traced automatically — no per-SDK wrapper needed.
+ *
+ * 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.
+ *
+ * **Design: eager creation, deferred completion.** The apo span is created
+ * at `onStart` (when initial attributes like tool name and model are
+ * available). The span is ended at `onEnd` with the final attributes
+ * (results, tokens, text). This gives correct ordering: parent spans
+ * are created before children, matching the real call hierarchy.
+ *
+ * @module
+ */
+interface OTelSpanContext {
+    spanId: string;
+    traceId: string;
+    traceFlags: number;
+}
+interface OTelSpanStatus {
+    code: number;
+    message?: string;
+}
+interface OTelReadableSpan {
+    name: string;
+    spanContext(): OTelSpanContext;
+    parentSpanContext?: OTelSpanContext;
+    attributes: Record<string, unknown>;
+    status: OTelSpanStatus;
+    duration: [number, number];
+    startTime: [number, number];
+    ended: boolean;
+}
+interface OTelSpan extends OTelReadableSpan {
+    setAttribute(key: string, value: unknown): this;
+    setAttributes(attributes: Record<string, unknown>): this;
+    setStatus(status: OTelSpanStatus): this;
+    recordException(exception: unknown): void;
+    updateName(name: string): this;
+    end(endTime?: unknown): void;
+    isRecording(): boolean;
+}
+interface OTelContext {
+    getValue(key: symbol): unknown;
+    setValue(key: symbol, value: unknown): OTelContext;
+    deleteValue(key: symbol): OTelContext;
+}
+interface OTelSpanProcessorLifecycle {
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/**
+ * A SpanProcessor that translates GenAI OTel spans into apo observations.
+ *
+ * Spans are created at `onStart` (eager) and completed at `onEnd`
+ * (deferred). This gives correct parent/child ordering — parent spans
+ * are created before their children, matching the real call hierarchy.
+ *
+ * If a span isn't load-bearing (not a GenAI tool/generation span), no
+ * apo span is created.
+ */
+declare class ApoSpanProcessor implements OTelSpanProcessorLifecycle {
+    private spanMap;
+    onStart(span: OTelSpan, _parentContext: OTelContext): void;
+    onEnd(span: OTelReadableSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+    /** Clear all state — for testing. */
+    reset(): void;
+}
+
+/**
+ * Registration API for the OTel-native tracing integration.
+ *
+ * Call {@link registerApoTracing} once at startup (e.g., in `startSession`
+ * or at module load). After this, any SDK that emits OTel spans during a run
+ * will be traced automatically — no per-SDK wrapper needed.
+ *
+ * @example
+ * ```ts
+ * import { registerApoTracing } from "@apo-ai/sdk/agent-task";
+ *
+ * async startSession(ctx) {
+ *   registerApoTracing(); // one line, once
+ *   return { async sendUserTurn(turn) { ... } };
+ * }
+ * ```
+ *
+ * @module
+ */
+
+interface RegisterApoTracingOptions {
+    /**
+     * Set as the global tracer provider (default: true).
+     * Set to false if the host app has its own OTel setup and you want to
+     * add apo's processor to an existing provider instead.
+     */
+    setGlobal?: boolean;
+}
+/**
+ * Register apo's OTel SpanProcessor. Idempotent — calling it more than
+ * once is a no-op.
+ *
+ * After registration, any OTel span created during an apo run (inside
+ * `withApoRun`) that matches the GenAI conventions (`ai.*` or `gen_ai.*`)
+ * is automatically translated and fed into the run's Flow.
+ */
+declare function registerApoTracing(_options?: RegisterApoTracingOptions): Promise<void>;
+/**
+ * Reset registration state — for testing only.
+ */
+declare function resetApoTracing(): void;
+
+/**
+ * Per-run context propagation via Node's AsyncLocalStorage.
+ *
+ * The OTel {@link ApoSpanProcessor} is global — it doesn't know which run a
+ * span belongs to. This module solves that: {@link withApoRun} establishes
+ * the run's trace context on AsyncLocalStorage, and any code called during
+ * the run (including the processor's `onStart`/`onEnd`) can read it via
+ * {@link getActiveApoRun}.
+ *
+ * This is the same propagation mechanism OTel's own
+ * `AsyncLocalStorageContextManager` uses under the hood.
+ *
+ * @module
+ */
+
+interface ApoRunContext {
+    /** The tee'd trace context for this run. */
+    trace: AgentTaskTraceContext;
+    /** The parent span id (the run's root span or the current turn span). */
+    parentSpanId?: string;
+    /** The task id, surfaced in span metadata. */
+    taskId?: string;
+    /** The current turn number, surfaced in span metadata. */
+    turnNumber?: number;
+}
+/**
+ * Run `fn` with `ctx` as the active apo run context. Any code inside `fn`
+ * (including across `await` boundaries) can call {@link getActiveApoRun}
+ * to retrieve it.
+ */
+declare function withApoRun<T>(ctx: ApoRunContext, fn: () => Promise<T>): Promise<T>;
+/**
+ * Run `fn` synchronously with `ctx` as the active apo run context.
+ */
+declare function withApoRunSync<T>(ctx: ApoRunContext, fn: () => T): T;
+/**
+ * Get the active run context, or `undefined` if called outside a run.
+ *
+ * This is what the {@link ApoSpanProcessor} calls in `onStart`/`onEnd` to
+ * know which run a span belongs to.
+ */
+declare function getActiveApoRun(): ApoRunContext | undefined;
+
+/**
+ * canonical Task Revision manifest.
+ *
+ * Pure, dependency-free canonicalizer. Both this module and its Python twin
+ * (`backend/apo/execution/task_revision_manifest.py`) MUST produce
+ * byte-identical canonical JSON and digests for every fixture under
+ * `specs/contracts/task-revision/v1/cases/`.
+ *
+ * Canonicalization rules:
+ *   - `/` path separators (caller `\` normalized to `/`);
+ *   - Unicode NFC normalization of the path;
+ *   - bytewise lexical ordering of normalized UTF-8 paths (NOT UTF-16 —
+ *     diverges for codepoints > U+007F);
+ *   - exact file-byte SHA-256 (lowercase hex);
+ *   - mode reduced to `regular` | `executable`;
+ *   - ownership, timestamps, inode metadata, and absolute paths excluded.
+ *
+ * `contentSha256` is the SHA-256 of the compact canonical JSON built from
+ * `schemaVersion` and the sorted `files` array. The `summary` block is NOT
+ * part of source identity.
+ */
+type ModeClass = "regular" | "executable";
+interface ManifestFile {
+    path: string;
+    sizeBytes: number;
+    sha256: string;
+    modeClass: ModeClass;
+}
+interface TaskRevisionManifestV1 {
+    schemaVersion: 1;
+    files: ManifestFile[];
+    summary: {
+        fileCount: number;
+        uncompressedSizeBytes: number;
+        excludedFileCount: number;
+        excludedDirectoryCount: number;
+    };
+}
+/** Caller-reported file, before canonicalization. `content` is the exact bytes. */
+interface ManifestFileInput {
+    path: string;
+    modeClass: ModeClass;
+    content: Uint8Array;
+}
+/**
+ * Normalize a caller-reported path to canonical POSIX + NFC form.
+ * Validation (no leading slash, no `.`/`..` segments) is the filesystem
+ * walker's responsibility; this function only makes representation canonical.
+ */
+declare function normalizeManifestPath(path: string): string;
+/** SHA-256 of exact bytes, lowercase hex. */
+declare function sha256Hex(bytes: Uint8Array): string;
+/**
+ * Build the canonical V1 manifest from already-included files. Exclusion
+ * counts default to zero; the filesystem walker supplies real counts when it
+ * wraps this via `withExclusionCounts`.
+ */
+declare function buildManifest(files: ManifestFileInput[], summary?: {
+    excludedFileCount: number;
+    excludedDirectoryCount: number;
+}): TaskRevisionManifestV1;
+/**
+ * Compact canonical JSON over `schemaVersion` + the sorted `files` array only.
+ * Object keys are alphabetical at every level; no whitespace; non-ASCII
+ * emitted as UTF-8 (matches Python `json.dumps(sort_keys=True,
+ * ensure_ascii=False, separators=(",", ":"))`). The `summary` block is
+ * intentionally excluded from source identity.
+ */
+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 LoadedTask, type ManifestFile, type ManifestFileInput, type Matcher, type ModeClass, type NameMatcher, type OpenAIMessage, type PreparedTaskResult, type RegisterApoTracingOptions, 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, resetApoTracing, resetFlowChecks, resetTaskRegistry, resetTaskTurn, resolveTurn, runAgentTaskCli, runTask, runTaskDir, satisfies, sha256Hex, similarity, task, defineCheck as test, turn, withApoRun, withApoRunSync };