/**
 * Lightweight polling helper used by the SDK runner to pre-load OTel
 * spans into the `traces` fixture for deterministic test bodies (#230).
 *
 * This is a thinner cousin of `tracePollingManager.startPolling`:
 *   - no judge wiring, no report storage updates, no trajectory rebuild
 *   - returns a result object that includes the **last error message**
 *     when polling never produced spans, so the caller can build a
 *     specific `unavailableTracesAccessor("fetch failed: …")` reason
 *     instead of a generic "no spans found"
 *
 * **Defaults are deliberately faster than the judge poller** in
 * `services/traces/tracePoller.ts`. The judge runs as a background
 * task while the user already sees a "pending" badge; ten minutes of
 * polling there is fine. The SDK fixture pre-load, however, is
 * synchronous inside the test body — every test waits on it before
 * its first assertion can run, so we cap the default budget at
 * ~10 seconds (10 × 1s). Users can still bump this via `tracePolling`
 * on the agent config or via `TRACE_POLL_INTERVAL_MS` /
 * `TRACE_POLL_MAX_ATTEMPTS` env vars (the same vars the judge poller
 * honours), and a hard `MAX_POLL_CEILING` mirrors the one in
 * `tracePoller.ts` so a misconfigured agent can't block a test for
 * an unbounded time.
 */
import type { Span } from '../../types/index.js';
/**
 * Strategy-C correlation input: an agent's OTel `service.name` plus the run's
 * wall-clock window. Used as a fallback (and union) when the agent's spans are
 * not tagged with the connector `runId` (Strategy B) — e.g. Claude Code / any
 * subprocess agent whose OTel SDK emits its own trace and never sees our runId.
 * Mirrors the `windowAgents` clause the run-report Traces tab already issues.
 */
export interface TraceWindowAgent {
    serviceName: string;
    startedAt: number;
    endedAt: number;
    /** Strategy D: precise per-run correlator (e.g. Claude Code `session.id`). */
    sessionId?: string;
}
/**
 * Hard ceiling on `maxAttempts`, mirroring the constant in
 * `services/traces/tracePoller.ts`. Prevents a misconfigured agent
 * (e.g. `tracePolling.maxAttempts: 10_000`) from blocking a test body
 * indefinitely.
 */
export declare const SDK_TRACE_POLL_CEILING = 60;
/** Default interval between polling attempts. ~1s for SDK interactivity. */
export declare const SDK_DEFAULT_POLL_INTERVAL_MS: number;
/** Default attempt budget. 10 attempts × ~1s ≈ 10s total for SDK pre-load. */
export declare const SDK_DEFAULT_MAX_ATTEMPTS: number;
export interface FetchSpansForRunOptions {
    /** Total number of attempts. Capped at {@link SDK_TRACE_POLL_CEILING}. */
    maxAttempts?: number;
    /** Delay between attempts in ms. */
    intervalMs?: number;
    /**
     * Strategy-C fallback: when provided, each poll unions the `runId` clause
     * with a service-name + time-window clause. This is what lets the SDK
     * `traces` fixture (and therefore the judge) actually receive spans from
     * agents like Claude Code whose OTel spans carry their own traceId +
     * `service.name` but NOT our connector `runId`. Without this, runId-only
     * correlation returns 0 spans and the judge never sees the trace (#XXX).
     */
    windowAgents?: TraceWindowAgent[];
}
export interface FetchSpansForRunResult {
    /** Spans returned on the first non-empty attempt, or `[]` on timeout / error. */
    spans: Span[];
    /**
     * If `spans` is empty, the message of the last error thrown by
     * `fetchTracesByRunIds` (auth failure, 5xx, network down, etc.).
     * `undefined` when polling completed without errors but the trace
     * backend simply had no spans for this `runId` yet — in that case the
     * caller should report a "no spans found" reason rather than a "fetch
     * failed" reason.
     */
    lastError?: string;
}
/**
 * Poll for spans associated with a single agent runId. Resolves with
 * the spans on the first non-empty fetch, or with `{ spans: [],
 * lastError? }` after `maxAttempts` of empty / failing responses.
 * Never throws.
 */
export declare function fetchSpansForRun(runId: string | undefined, options?: FetchSpansForRunOptions): Promise<FetchSpansForRunResult>;
//# sourceMappingURL=fetchSpansForRun.d.ts.map