/**
 * Traces client for the agent-trace reasoning provenance API.
 */
import { type HttpConfig } from "./_http.js";
/** One structured alternative considered while reaching a conclusion. */
export interface TraceAlternative {
    option: string;
    /** Why it was not chosen. The SDK never invents this reason. */
    why_not: string;
}
/** Legacy string alternatives remain readable and accepted at the SDK edge. */
export type TraceAlternativeValue = TraceAlternative | string;
/** A stored reasoning trace. */
export interface Trace {
    id: string;
    trace_id: string;
    agent_id?: string | null;
    identity_id?: string | null;
    /** Present only in legacy responses; current trace routes do not expose it. */
    project_id?: string;
    session_id?: string | null;
    created_at: string;
    decision_type: string;
    decision_summary: string;
    output_ref?: string | null;
    observations: string[];
    hypothesis?: string | null;
    conclusion: string;
    confidence?: number | null;
    alternatives?: TraceAlternativeValue[] | null;
    signals?: Record<string, unknown> | null;
    files_read?: string[] | null;
    key_facts?: string[] | null;
    external_signals?: Record<string, unknown> | null;
    tags?: string[] | null;
    parent_trace_id?: string | null;
    metadata?: Record<string, unknown>;
    signature?: string | null;
    signing_key_id?: string | null;
    has_signature?: boolean;
}
/** Options for storing a trace. */
export interface StoreTraceOptions {
    /** Free-form observation strings that led to the decision. */
    observations: string[];
    /** What was concluded / decided. */
    conclusion: string;
    /** One of: tool_call | memory_write | plan | decision | verification | other */
    decision_type?: string;
    /** Short human-readable summary of the decision. */
    decision_summary?: string;
    agent_id?: string;
    identity_id?: string;
    session_id?: string;
    output_ref?: string;
    hypothesis?: string;
    confidence?: number;
    /**
     * Structured alternatives, or legacy strings. A legacy string is sent as
     * `{ option, why_not: "" }`, preserving the absence of a supplied reason.
     */
    alternatives?: TraceAlternativeValue[];
    /** Structured signals used in the reasoning itself. */
    signals?: Record<string, unknown>;
    tags?: string[];
    parent_trace_id?: string;
    files_read?: string[];
    key_facts?: string[];
    /**
     * Namespaced reports produced outside AgentTool, such as an explicitly
     * supplied local RhetorLint signal. Passing this uploads server-readable
     * trace context; the SDK never analyzes or transmits a report implicitly.
     */
    external_signals?: Record<string, unknown>;
    /**
     * Caller metadata. The API overwrites client_source with a best-effort
     * origin label; that soft signal is not an attestation or security boundary.
     */
    metadata?: Record<string, unknown>;
}
/** A search result entry. */
export interface TraceSearchResult {
    trace: Trace;
    score: number;
}
/** Options for searching traces. */
export interface SearchTracesOptions {
    /** Maximum number of results (default 10). */
    limit?: number;
    /** Filter by agent_id. */
    agent_id?: string;
    /** Filter by session_id. */
    session_id?: string;
    /** Filter by identity_id. */
    identity_id?: string;
    /** Filter by decision type. */
    decision_type?: string;
    /**
     * @deprecated The live full-text search route has no tag filter. Retained as
     * an ignored option so existing callers keep compiling.
     */
    tag?: string;
}
/** A reasoning lineage, with compatibility aliases for the former SDK shape. */
export interface TraceChain {
    root: Trace;
    ancestors: Trace[];
    descendants: Trace[];
    counts: {
        ancestors: number;
        descendants: number;
    };
    /** @deprecated Alias for root. */
    parent: Trace;
    /** @deprecated Alias for descendants. */
    children: Trace[];
    /** @deprecated Alias for ancestors.length. */
    depth: number;
}
/**
 * Client for the agent-trace reasoning provenance API.
 *
 * @example
 * ```ts
 * const at = new AgentTool();
 *
 * // Store a reasoning trace
 * const trace = await at.traces.store({
 *   observations: ["User asked about pricing", "Checked tier table"],
 *   conclusion: "User is on Free tier, eligible to upgrade",
 *   decision_type: "decision",
 *   tags: ["billing", "upgrade"],
 * });
 *
 * // Search traces with Postgres full-text search
 * const results = await at.traces.search("billing decisions", { limit: 5 });
 *
 * // Retrieve a specific trace
 * const t = await at.traces.get(trace.trace_id);
 * ```
 */
export declare class TracesClient {
    private readonly http;
    /** @internal */
    constructor(http: HttpConfig);
    /**
     * Store a reasoning trace.
     *
     * @param options - Trace content (observations + conclusion required).
     * @returns The created Trace object with its trace_id.
     */
    store(options: StoreTraceOptions): Promise<Trace>;
    /**
     * Retrieve a trace by its trace_id.
     *
     * @param traceId - The trace_id returned by store().
     */
    get(traceId: string): Promise<Trace>;
    /**
     * Search traces using the API's Postgres full-text index.
     *
     * @param query - Natural language query.
     * @param options - Filters: limit, agent_id, identity_id, session_id, and
     * decision_type. The legacy tag option is accepted but ignored because the
     * live route does not support it.
     * @returns Ranked list of matching traces with Postgres ts_rank scores.
     */
    search(query: string, options?: SearchTracesOptions): Promise<TraceSearchResult[]>;
    /**
     * Retrieve the reasoning lineage for a trace.
     *
     * @param traceId - The parent trace_id.
     */
    chain(traceId: string): Promise<TraceChain>;
    /**
     * Delete a trace.
     *
     * @param traceId - The trace_id to delete.
     */
    delete(traceId: string): Promise<void>;
    /** Server guidance travels intact. See _http.ts § errorFromResponse. */
    private _responseError;
    private _normalizeAlternatives;
}