@adonis-agora/agent/dist/src/stores/lucid-governance-queries.d.ts

Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.

import { type GenuiStats } from '../genui-telemetry.js';
import type { ActorSpendRow, AgentGovernanceQueries, GovernanceRange, GovernanceThreadDetail, ListRunsFilter, ListRunsResult, ModelSpendRow, PendingApprovalRow, PendingApprovalsFilter, PerToolStatRow, RunDetail, RunReliability, ThreadActivityRow, ToolCallActivityRow, ToolStatsRange, UsageTrendPoint } from '../spi/governance-queries.js';
import type { AgentPricingStore } from '../spi/pricing-store.js';
import { type LucidDatabaseLike } from './lucid.js';
/** Options for {@link LucidGovernanceQueries}. */
export interface LucidGovernanceQueriesOptions {
    /**
     * Provision the shared agent tables on first use. Default `true` (the ecosystem convention). The
     * read-model aggregates the six shared tables; auto-provisioning here is what lets the governance
     * routes / dashboard answer on a fresh deploy before the first agent run. Set `false` for the migration.
     */
    autoCreateTables?: boolean;
}
/**
 * A production {@link AgentGovernanceQueries} — the read/analytics half of the store SPI — backed by
 * AdonisJS **Lucid** (Knex) over the same five agent tables {@link import('./lucid.js').LucidAgentStore}
 * writes. Like the store it touches only the structural {@link LucidDatabaseLike} slice, so
 * `@adonisjs/lucid` stays an *optional peer* (the factory casts the real `db` in).
 *
 * Cost is the token ledger priced against the current prices from the injected {@link AgentPricingStore}
 * (fetched once per query, exactly like the Drizzle/MikroORM references and the loop's cost fold), so a
 * host that binds its own pricing store controls the cost every governance surface reports. A
 * provider-reported `cost_usd` on a usage row always wins; an unpriced model contributes 0 cost (its
 * tokens still count). Omit the pricing store entirely for a zero-cost read-model. Aggregation is
 * in-process (like `quotaToday`) so UTC-day bucketing stays dialect-portable across SQLite/Postgres/MySQL
 * — the behavioral twin of {@link import('../testing/in-memory-governance-queries.js').InMemoryGovernanceQueries}.
 */
export declare class LucidGovernanceQueries implements AgentGovernanceQueries {
    private readonly db;
    private readonly pricingStore?;
    private readonly autoCreateTables;
    constructor(db: LucidDatabaseLike, pricingStore?: AgentPricingStore | undefined, options?: LucidGovernanceQueriesOptions);
    /** Provision the shared schema on first use (no-op when disabled), memoized across the stores. */
    private ready;
    /** Provision the shared schema now (what the agent provider calls at app start). Idempotent. */
    ensureSchema(): Promise<void>;
    private loadPricing;
    /** Provider-reported cost wins per row; otherwise the cache-aware token estimate (0 when unpriced). */
    private rowCost;
    /** The usage ledger rows whose `created_at` falls inside the inclusive UTC-day range. */
    private usageInRange;
    spendByModel(range: GovernanceRange): Promise<ModelSpendRow[]>;
    spendByActor(range: GovernanceRange): Promise<ActorSpendRow[]>;
    usageTrend(range: GovernanceRange): Promise<UsageTrendPoint[]>;
    /**
     * Newest-first recent tool calls, capped at `limit`. Resolves each call's `threadId` through its
     * owning message (the structural query slice has no `join`, so it's one lookup per call — bounded by
     * `limit`, mirroring the reference adapters' N+1 for the recent feeds).
     */
    recentToolCalls(limit: number): Promise<ToolCallActivityRow[]>;
    /**
     * Newest-first recent threads (soft-deleted excluded, mirroring `listThreads`/the reference), each
     * with its message count and rolled-up token total, capped at `limit`.
     */
    recentThreads(limit: number): Promise<ThreadActivityRow[]>;
    /**
     * Filterable, cursor-paginated run list, newest-first (`started_at` desc, then `id` desc for a
     * stable tiebreak). `after` is an opaque cursor (over the SAME filter set); a page fetches
     * `first + 1` rows to learn whether a next page exists. A store without recorded runs yields an
     * empty page.
     *
     * Forward-only, so the returned {@link CursorPage} always carries `prevCursor: null` /
     * `hasPrev: false` — see `src/pagination.ts`.
     */
    listRuns(filter?: ListRunsFilter): Promise<ListRunsResult>;
    /**
     * The full trace of one run: the run row plus every message / tool call / usage row stamped with
     * its `run_id` (oldest first), and the subset of tool calls still `pending_approval`. `null` when
     * the run is unknown.
     */
    runDetail(runId: string): Promise<RunDetail | null>;
    /**
     * Tool calls sitting `pending_approval`, oldest first (an inbox drains from the back). Each call's
     * owning actor is resolved through its run (`run_id → agent_run.actor_ref`), falling back to its
     * thread (`message → agent_thread.actor_ref`) for a call recorded before run tracking. The `actor`
     * filter is applied after resolution; `limit` caps the returned inbox.
     */
    pendingApprovals(filter?: PendingApprovalsFilter): Promise<PendingApprovalRow[]>;
    /**
     * Per-tool call/failure/rejection/latency rollup over the (optional) range, highest call count
     * first. `avgDurationMs` is the mean `execution_ms` across calls that recorded one; `null` when
     * none did.
     */
    genuiStats(range: GovernanceRange): Promise<GenuiStats>;
    perToolStats(range?: ToolStatsRange): Promise<PerToolStatRow[]>;
    /**
     * Success / failure / cancel rates + mean settled-run duration over the (optional) range, bucketed
     * on `started_at`, plus a per-agent breakdown, a daily runs/failed trend, turn latency and failures
     * by code over the same rows. A store without recorded runs yields all zeros / `null` duration /
     * empty breakdown+trend+codes.
     */
    runReliability(range?: ToolStatsRange): Promise<RunReliability>;
    /**
     * The thread governance drill-down: metadata + a LIFETIME usage rollup (every usage row ever
     * recorded for the thread, not range-scoped) + its most recent runs/messages. `null` when the
     * thread is unknown. Soft-deleted threads still resolve (with `deleted: true`), mirroring
     * `runDetail`'s "the record exists, render it" posture.
     */
    threadDetail(threadId: string): Promise<GovernanceThreadDetail | null>;
}
//# sourceMappingURL=lucid-governance-queries.d.ts.map