/**
 * Execution-trace self-reporting — tell the backend what this invocation
 * actually did, so a locally-run pipeline is not a blind spot.
 *
 * Why this exists: the cloud agent records every tool call, its arguments AND
 * its result into `media_chat_turn_trace` (ab-agent/src/trace-persist.ts). The
 * local path records nothing — a take created from codex / claude code has an
 * empty conversation, zero tool calls and zero credits in the analytics tables,
 * so every session-level metric silently excludes it.
 *
 * What we can honestly report and what we cannot: the CLI is a child process
 * spawned once per skill call. It never sees the user's prompt or the host's
 * reply — those live in the host's own transcript. So this module reports the
 * one thing it genuinely observes: the invocation itself.
 *
 * See docs/cli-session-record-design.md §5.
 */
import { type HttpContext } from '../http.js';
import type { ParsedArgs } from '../argv.js';
import type { EnsuredTake } from './take.js';
export interface TraceOptions {
    skillName: string;
    args: ParsedArgs;
    take: EnsuredTake;
    ctx: HttpContext;
}
/**
 * Whether this invocation should report at all.
 *
 * The rule is deliberately narrow: report only when THIS process resolved the
 * take. Everything else is already covered by someone else —
 *   - under the cloud agent, CONVERSATION_ID arrives pre-set and ab-agent's own
 *     TurnTracer already recorded the very same call;
 *   - a nested `gen-image` spawned by prepare-video-assets inherits its
 *     parent's CONVERSATION_ID, and the parent's row already covers it.
 * Since runner.ts only builds a tracer after resolving a take itself, this
 * function just honours the kill switch.
 */
export declare function tracingEnabled(env?: NodeJS.ProcessEnv): boolean;
/**
 * Collects one invocation's evidence and posts it as a single turn.
 *
 * Lifecycle (runner.ts): `begin()` → output flows through the tap → `finish()`
 * in a finally block. Every failure mode ends in a warning on stderr: a lost
 * trace row must never cost the user a render they already paid for.
 */
export declare class InvocationTrace {
    private readonly opts;
    private chunks;
    private restore;
    private flushed;
    private constructor();
    /** Returns null when tracing is off — callers can then skip output capture entirely. */
    static begin(opts: TraceOptions): InvocationTrace | null;
    /**
     * Tap both output streams.
     *
     * One tap covers both dispatch paths: in-process handlers write here
     * directly, and the Python child's piped output is re-emitted through the
     * same `write` (see runner.ts). Restored in finish().
     */
    installCapture(): void;
    /** Feed captured output. Keeps a bounded tail — the decisive line is the last one. */
    absorb(chunk: unknown): void;
    /**
     * Emit the turn. Idempotent; never throws.
     *
     * `error` is the dispatcher's caught exception when there is one — a Python
     * child that exits non-zero gives us no exception, only its output, which is
     * exactly why the tail buffer exists.
     */
    finish(exitCode: number, durationMs: number, error?: unknown): Promise<void>;
}
/**
 * Flags → a trace-safe object.
 *
 * Credentials are dropped outright; long strings are cut to their opening
 * because an argument like `--prompt` is *content*, and this table is evidence,
 * not an archive of what the user wrote.
 */
export declare function sanitiseArgs(args: ParsedArgs): Record<string, unknown>;
/**
 * Captured output → the tail we store.
 *
 * Two transformations before truncating, both about spending the 16KB on
 * things a human would read:
 *   - progress lines are the machine protocol — one fat JSON object per phase,
 *     marked by a `__progress__` field (progress.ts, and the same shape from the
 *     Python skills). Their payload is noise here, but WHICH PHASE a failed run
 *     reached is the single most useful fact about it, so the line collapses to
 *     its phase name instead of being dropped.
 *   - `__diagnostic_v1__` lines are our own structured log of this very run;
 *     keeping them would store the same verdict twice.
 *
 * Then keeps the TAIL, unlike ab-agent's head-first cleanText: a command's
 * verdict — the error, or the URL it produced — is its last line.
 */
export declare function condense(raw: string): string;