/**
 * Reader (and limited writer) for `~/.blockrun/cost_log.jsonl` — the
 * append-only ledger of every settled x402 payment.
 *
 * History: this file was originally SDK-only territory. `@blockrun/llm`'s
 * internal `appendCostLog` writes one line per micropayment when callers
 * use SDK helper methods (modal sandbox, prediction market, exa, etc.).
 * But Franklin's main LLM stream — both the in-process agent loop
 * (`src/agent/llm.ts`) and the proxy server (`src/proxy/server.ts`) —
 * have **their own** x402 signers that bypass the SDK entirely. Verified
 * 2026-05-09 on a real machine: a single paid agent turn dropped the
 * wallet by $0.001 and updated `franklin-stats.json` correctly, but
 * cost_log.jsonl gained zero entries. So cost_log was never the
 * "wallet truth" it advertised — it was an SDK-subset.
 *
 * Fix (2026-05-09): expose `appendSettlementRow` so the agent and proxy
 * signers can write the same shape the SDK does. The format contract
 * (snake_case `cost_usd`, `ts` in unix seconds with subsecond precision,
 * one JSON object per line) is preserved exactly so both writers
 * interleave cleanly. Order in the file follows wall-clock arrival.
 *
 * Responsibility: read + append-only write. We never trim or rotate
 * cost_log.jsonl — that contract still belongs to the SDK / hygiene.
 */
export interface SettlementRow {
    /** Endpoint path that was paid for, e.g. `/v1/chat/completions`. */
    endpoint: string;
    /** USD settled on-chain via x402. */
    costUsd: number;
    /** Unix milliseconds (normalized — SDK writes seconds). */
    ts: number;
    /** Wallet that signed (lowercased). Used for test-wallet filtering. */
    wallet?: string;
    /** Model that was charged (e.g. `openai/gpt-5.5`). */
    model?: string;
    /** Which client wrote the row (LLMClient / AgentClient / ProxyClient / AsyncLLMClient). */
    clientKind?: string;
}
export interface SettlementSummary {
    /** Path to cost_log.jsonl (or the fallback location). */
    path: string;
    /** Total entries read. */
    count: number;
    /** Sum of `costUsd` across all rows in window. */
    totalUsd: number;
    /** Per-endpoint breakdown sorted by cost descending. */
    byEndpoint: Array<{
        endpoint: string;
        count: number;
        costUsd: number;
    }>;
    /** First and last timestamps observed in the window (unix ms), or null. */
    firstTs: number | null;
    lastTs: number | null;
}
interface ReadOptions {
    /** Override the cost_log path (for tests). Defaults to ~/.blockrun/cost_log.jsonl. */
    path?: string;
    sinceMs?: number;
    untilMs?: number;
}
/**
 * Load + parse cost_log.jsonl. Optional time window in unix milliseconds.
 * Skips malformed lines silently (the SDK's JSONL writer is well-behaved
 * but we don't want a single corrupted line to nuke the whole readout).
 *
 * Returns an empty list if the file doesn't exist — callers should treat
 * that as "no SDK ledger available" rather than an error, since the file
 * is only created on the first paid call.
 */
export declare function loadSdkSettlements(opts?: ReadOptions): SettlementRow[];
/**
 * Optional metadata fields the SDK writes alongside `endpoint` / `cost_usd`.
 * Adding these to agent + proxy entries keeps cost_log.jsonl uniformly
 * queryable (group by model, filter by wallet, etc.). Verified 2026-05-10
 * against a real cost_log: the SDK writes
 *   {endpoint, cost_usd, model, wallet, network, client_kind}
 * Without these on agent rows you can't tell which model burned a $0.001
 * — the row is just `/v1/messages: 0.001`. With them, every line is a
 * complete forensic record.
 */
export interface SettlementMeta {
    model?: string;
    wallet?: string;
    network?: string;
    client_kind?: string;
}
/**
 * Append one settlement row to ~/.blockrun/cost_log.jsonl in the same
 * shape `@blockrun/llm`'s internal `appendCostLog` writes. Best-effort:
 * silently swallows fs errors so a logging failure never breaks the
 * paid call that just succeeded. Costs <= 0 are treated as no-op (no
 * point logging $0 — the file's purpose is "what was actually paid").
 *
 * Honors FRANKLIN_NO_AUDIT=1 the same way `appendAudit` and `recordUsage`
 * do, so test runs (test/e2e.mjs sets this) don't pollute the user's
 * real cost_log. Verified 2026-05-10 on a real machine: two
 * `/v1/messages: $0.000001` rows leaked into the user's cost_log from
 * a paid e2e run because this gate was missing — paid e2e was hitting
 * the real gateway with a real wallet, but the test framework expected
 * NO writes to land. Restoring the gate keeps cost_log a clean ledger
 * of REAL traffic.
 */
export declare function appendSettlementRow(endpoint: string, costUsd: number, meta?: SettlementMeta): void;
/** Aggregate the SDK ledger into a single summary object. */
export declare function summarizeSdkSettlements(opts?: ReadOptions): SettlementSummary;
export {};