/**
 * An OPTIONAL bridge from the agent runtime's {@link RunEvent} stream to the
 * tracing layer's {@link Recorder} / {@link Segment} model.
 *
 * The runtime publishes a flat stream of {@link RunEvent}s (snapshots, deltas,
 * tool lifecycle, settle/fault). {@link traceAgentRun} subscribes to that stream
 * and *projects* it into nested {@link Segment}s on a {@link Recorder}: a `run`
 * segment that spans a whole prompt-to-settlement interaction, an `inference`
 * child per model turn, and an `action` child per tool invocation. The result is
 * a hierarchical trace that flows onto the recorder's {@link SignalChannel} for
 * any {@link import('../sinks/base').Sink} to drain.
 *
 * The mapping is deliberately *best-effort* and decoupled: it reads only the
 * public {@link RunEvent} shape (imported from "../../runtime") and never reaches
 * into runtime internals. It tolerates events arriving in any order — a missing
 * `tool_started` for a `tool_finished`, a `settled` with an inference still
 * open, repeated terminal events — by closing whatever is open and ignoring the
 * rest. Wiring it is optional: nothing in the runtime depends on it.
 *
 * This is the one place the tracing subsystem is allowed to know the runtime's
 * event vocabulary; the tracing core (signal/channel/recorder/…) stays entirely
 * runtime-agnostic.
 */
import type { RunEvent } from "../../runtime";
import type { Recorder } from "../recorder/recorder";
/**
 * Subscribe to a runtime {@link RunEvent} source and call `handler` for each
 * event, returning a disposer that detaches the subscription. This matches the
 * shape of `Agent.subscribe` without importing the `Agent` type, so the adapter
 * stays decoupled from the conductor.
 */
export type RunEventSubscribe = (handler: (event: RunEvent) => void) => () => void;
/**
 * Project a runtime {@link RunEvent} stream onto a {@link Recorder} as nested
 * {@link Segment}s, returning a disposer that detaches and tidies up.
 *
 * Lifecycle mapping (best-effort):
 *
 * - **run** — opened lazily on the first event of a fresh run (or the first
 *   `snapshot`/`settled`/`faulted` carrying a `runId`), named after the run.
 *   Closed on `settled` (status `ok`) or `faulted` (status `error`).
 * - **inference** — a child of the run, opened when the run enters its
 *   `invoking` phase (a model turn begins) and closed when the model output is
 *   consumed (the run leaves `streaming` for `dispatching`/`compacting`, or the
 *   run terminates). Streaming deltas (`text_delta`/`thinking_delta`) are folded
 *   onto the open inference as attribute counts.
 * - **action** — a child of the run, opened on `tool_started` and closed on the
 *   matching `tool_finished` (status `error` when the outcome `isError`).
 *
 * Calling the returned disposer (or the stream ending without a terminal event)
 * closes any still-open segments so nothing dangles. The function never throws
 * on malformed input; it simply maps what it can.
 */
export declare function traceAgentRun(recorder: Recorder, subscribe: RunEventSubscribe): () => void;
