/**
 * `@ai-matrx/agents/mandates/runs` — THE ONE READ of run history: `mandate.run_history`.
 *
 * One mandate's runs, or one agent's runs across every mandate and direct use (exactly one of the
 * two; the database refuses neither or both with 22023). No new log: the database reads the
 * records every funnel already writes (chat.user_request for agent and chat starts, held code
 * calls and `run_mandate`; workflow.run for every workflow Holder run). Which level decided each
 * run is stamped by aidream at the resolution; runs recorded before that stamp come back with
 * `rung: null` — "not recorded", never a guess.
 *
 * Views are SEATS, and the database checks each one:
 *   mine      the caller's own runs          (a member)
 *   org       every run in one organization  (its owner/admin)
 *   platform  every run on the platform      (admin section only — never "mine")
 *
 * Moved from matrx-frontend features/mandates/run-history/service.ts (2026-10-12) so the desktop
 * app (Agents › an agent › Runs) reads the same rows through the same parser. HEADLESS: the host
 * passes its own supabase client (anything with `schema(name).rpc(fn, args)`), never a global.
 * Every field of the answer is narrowed, never cast.
 */
type RunHistoryView = "mine" | "org" | "platform";
type RunStatus = "succeeded" | "warned" | "failed" | "stopped" | "waiting" | "running";
type RunRung = "system" | "org" | "user" | "run";
type RunSort = "started_at" | "duration" | "cost" | "status" | "level";
declare const RUN_STATUSES: readonly RunStatus[];
interface MandateRun {
    /** `agent_run` = an agent run labeled with the mandate that kept no conversation. */
    runKind: "conversation" | "workflow" | "agent_run";
    runId: string;
    startedAt: string;
    completedAt: string | null;
    status: RunStatus;
    rawStatus: string | null;
    error: string | null;
    ranById: string | null;
    ranByName: string | null;
    ranByKind: "person" | "system";
    organizationId: string | null;
    organizationName: string | null;
    /** null = recorded before the level was stamped (2026-09-27). */
    rung: RunRung | null;
    holderType: "agent" | "workflow";
    holderId: string | null;
    holderName: string | null;
    holderAgentType: string | null;
    outputWarned: boolean;
    outputMissingKeys: string[];
    cost: number | null;
    durationMs: number | null;
    tokens: number | null;
    /** The mandate this run served; null = no mandate named it. */
    mandateKey: string | null;
    /**
     * What the server's attribution funnel decided for a run with no mandate
     * (`mandate_attribution`): `direct` = a person or fixture started the agent by id,
     * `unknown` = the funnel could not decide. null = never stamped — never read as `direct`.
     */
    attribution: string | null;
    /** The door that made a `direct` run direct (e.g. `matrx-frontend/agent-runner`). */
    directDoor: string | null;
    /** How the list found it: `holder_agent` = a run of its Holder agent with no mandate name. */
    foundBy: "mandate" | "holder_agent" | "agent";
    /** The run's answer, one line (≤240 chars); null when none was kept. */
    outputPreview: string | null;
    conversationId: string | null;
    /** The conversation holds messages to read (a background run keeps none). */
    hasTranscript: boolean;
}
interface RunFacet {
    id: string;
    name: string | null;
    count: number;
}
interface MandateRunPage {
    total: number;
    rows: MandateRun[];
    facets: {
        organizations: RunFacet[];
        people: RunFacet[];
    } | null;
}
interface RunsQuery {
    /** Exactly one: a mandate's runs, or one agent's. */
    scope: {
        mandateKey: string;
    } | {
        agentId: string;
    };
    view: RunHistoryView;
    organizationId?: string | null;
    userId?: string | null;
    status?: RunStatus | null;
    sort?: RunSort;
    descending?: boolean;
    limit?: number;
    offset?: number;
}
/** The database's refusal or failure, with its own words (code, detail, hint). */
declare class RunHistoryReadError extends Error {
    readonly name = "RunHistoryReadError";
    readonly code: string | null;
    readonly detail: string | null;
    readonly hint: string | null;
    constructor(init: {
        message: string;
        code?: string | null;
        detail?: string | null;
        hint?: string | null;
    });
}
/** The one call the read makes: a supabase-js client fits it as is. */
interface RunHistoryClient {
    schema(name: "mandate"): {
        rpc(fn: "run_history", args: Record<string, unknown>): PromiseLike<{
            data: unknown;
            error: {
                message: string;
                code?: string | null;
                details?: string | null;
                hint?: string | null;
            } | null;
        }>;
    };
}
declare function fetchRuns(client: RunHistoryClient, query: RunsQuery): Promise<MandateRunPage>;
/**
 * The server stores a run's error as a JSON string (`{"error_type":…,"message":…}`) on many
 * paths; the row shows its sentence, never the raw JSON. The SQL cuts the text at 300
 * characters, so a cut JSON string is read by its message field.
 */
declare function readableError(text: string | null): string | null;
/** The database's answer as a page; throws when it is not one (never an empty page by accident). */
declare function parseRunPage(data: unknown): MandateRunPage;

export { RUN_STATUSES, RunHistoryReadError, fetchRuns, parseRunPage, readableError };
export type { MandateRun, MandateRunPage, RunFacet, RunHistoryClient, RunHistoryView, RunRung, RunSort, RunStatus, RunsQuery };