import { type StagePreparation, type ToolExecutionReceipt } from "./preparation.ts";
import type { AgentState, SkillGraph } from "./graph.ts";
import { type CursorHookSummary } from "./cursor-hook.ts";
export declare const TRACE_SCHEMA_VERSION: 1;
export declare const TRACE_EVENT_SCHEMA_VERSION: 1;
export declare const TRACE_DIR_REL = "agent/runs/traces";
export declare const TRACE_ACTIVE_REL = "agent/runs/traces/active.json";
export declare const TRACE_LAST_REL = "agent/runs/traces/last.json";
export type TraceStatus = "recording" | "stopped" | "superseded";
export type EvidencePresence = "present" | "absent" | "ambiguous";
export type AgentActionVisibility = "unobserved" | "partial" | "unknown";
export type FactVisibility = "observed_by_kernel" | "reported_by_cursor_export" | "inferred_from_file_changes" | "observed_by_cursor_hook";
export type PromptFidelity = "verified" | "unverified" | "missing";
export type TraceEventType = "stage_prepared" | "stage_completed" | "tool_completed" | "stage_invalidated" | "run_finished" | "cursor_attached";
export interface CursorExportInspection {
    format: "unverified-markdown";
    userPrompt: EvidencePresence;
    toolNames: EvidencePresence;
    toolArguments: EvidencePresence;
    toolResults: EvidencePresence;
    timestamps: EvidencePresence;
    chatIdentity: EvidencePresence;
    agentActions: AgentActionVisibility;
    notes: string[];
}
export interface CursorExportRecord {
    sourceFilename: string;
    storedPath: string;
    hash: string;
    importedAt: string;
    bytes: number;
    preparationIds?: string[];
    inspection: CursorExportInspection;
}
export interface TraceManifest {
    schemaVersion: 1;
    traceId: string;
    site: string;
    sitePath: string;
    startedAt: string;
    endedAt?: string;
    kernelRevision: string;
    graphVersion: number;
    label?: string;
    status: TraceStatus;
    cursorExports: CursorExportRecord[];
    ownedPreparationIds: string[];
    promptSnapshots: Record<string, {
        path: string;
        hash: string;
        bytes: number;
        publishedHash?: string;
        fidelity: PromptFidelity;
    }>;
    warnings: Array<{
        timestamp: string;
        message: string;
        kind?: string;
        preparationId?: string;
        expectedHash?: string;
        actualHash?: string;
        snapshotPath?: string;
    }>;
}
export interface TraceActiveMarker {
    schemaVersion: 1;
    traceId: string;
    startedAt: string;
}
export interface TraceLastMarker {
    schemaVersion: 1;
    traceId: string;
    stoppedAt: string;
    status: "stopped" | "superseded";
}
export interface TraceEvent {
    schemaVersion: 1;
    type: TraceEventType;
    timestamp: string;
    traceId: string;
    nodeId?: string;
    preparationId?: string;
    attempt?: number;
    reused?: boolean;
    result?: string;
    failures?: string[];
    failureSummary?: string;
    promptHash?: string;
    promptPath?: string;
    promptBytes?: number;
    estimatedPromptTokens?: number;
    hashMismatch?: boolean;
    promptFidelity?: PromptFidelity;
    publishedPromptHash?: string;
    snapshotPromptHash?: string;
    receiptPath?: string;
    logPath?: string;
    usagePath?: string;
    durationMs?: number;
    exitCode?: number;
    command?: string[];
    stateStatus?: string;
    repairTarget?: string;
    changedFiles?: {
        created: string[];
        modified: string[];
        deleted: string[];
    };
    agentTokens: "unknown" | {
        input?: number;
        output?: number;
        measured: boolean;
        source: string;
    };
    visibility: FactVisibility;
    sourceFilename?: string;
    storedPath?: string;
    notes?: string[];
}
export interface TraceStageSummary {
    nodeId: string;
    preparationId?: string;
    attempt: number;
    kind?: string;
    result?: string;
    preparedAt?: string;
    completedAt?: string;
    elapsedMs?: number;
    promptBytes?: number;
    estimatedPromptTokens?: number;
    toolDurationMs?: number;
    failures: string[];
    repairTarget?: string;
    changedFiles?: {
        created: string[];
        modified: string[];
        deleted: string[];
    };
    evidence: Array<{
        fact: string;
        visibility: FactVisibility;
        path?: string;
    }>;
    agentTokens: "unknown" | {
        input?: number;
        output?: number;
        measured: boolean;
        source: string;
    };
    promptFidelity?: PromptFidelity;
    publishedPromptHash?: string;
    snapshotPromptHash?: string;
    missing?: string[];
    cursorActions?: {
        reads: {
            count: number;
            durationMs: number;
        };
        searches: {
            count: number;
            durationMs: number;
        };
        writes: {
            count: number;
            durationMs: number;
        };
        shell: {
            count: number;
            durationMs: number;
        };
        mcp: {
            count: number;
            durationMs: number;
        };
        retries: number;
        eventIds: string[];
        outsideExpectedWrites: string[];
    };
}
export interface TraceSummary {
    schemaVersion: 1;
    traceId: string;
    status: TraceStatus;
    site: string;
    startedAt: string;
    endedAt?: string;
    kernelRevision: string;
    graphVersion: number;
    label?: string;
    agentActions: AgentActionVisibility;
    agentTokens: "unknown";
    visibilityGaps: string[];
    stages: TraceStageSummary[];
    repeatedFailures: Array<{
        text: string;
        count: number;
    }>;
    longStages: Array<{
        nodeId: string;
        preparationId?: string;
        elapsedMs: number;
    }>;
    promptNotes: string[];
    promptIntegrityWarnings: Array<{
        preparationId: string;
        expectedHash: string;
        actualHash: string;
        snapshotPath: string;
        message: string;
    }>;
    cursorExports: CursorExportRecord[];
    cursorHooks: CursorHookSummary;
    evidencePaths: string[];
}
export interface TraceCliResult {
    handled: boolean;
    exitCode: number;
    message?: string;
}
export declare function siteRel(root: string, absPath: string): string;
export declare function tracesRoot(root: string): string;
export declare function activeMarkerPath(root: string): string;
export declare function lastMarkerPath(root: string): string;
export declare function traceDir(root: string, traceId: string): string;
export declare function readKernelRevision(kernel: string): string;
/** Append one JSONL line. Sequential process reopen is safe on Windows. */
export declare function appendJsonl(path: string, value: unknown): void;
export declare function loadActiveMarker(root: string): TraceActiveMarker | undefined;
export declare function loadLastMarker(root: string): TraceLastMarker | undefined;
export declare function loadManifest(root: string, traceId: string): TraceManifest | undefined;
/**
 * Active recording session wins. Otherwise the most recently stopped/superseded
 * trace. Ambiguous or missing state requires `--trace <id>`.
 */
export declare function resolveDefaultTraceId(root: string): {
    traceId: string;
    source: "active" | "last";
} | {
    error: string;
};
export declare function loadRecordingSession(root: string): {
    marker: TraceActiveMarker;
    manifest: TraceManifest;
} | undefined;
export declare function withTraceSafe(root: string, fn: () => void): void;
export declare function startTraceSession(opts: {
    root: string;
    kernel: string;
    graph: SkillGraph;
    label?: string;
    kernelRevision?: string;
}): {
    traceId: string;
    resumed: false;
    superseded?: string;
};
export declare function stopTraceSession(root: string): {
    traceId: string;
    alreadyStopped?: boolean;
} | undefined;
export declare function readEvents(root: string, traceId: string): TraceEvent[];
export declare function snapshotPreparedPrompt(root: string, preparation: Pick<StagePreparation, "id" | "promptHash">): {
    path: string;
    hash: string;
    bytes: number;
    hashMismatch: boolean;
    alreadyPresent: boolean;
    publishedHash?: string;
    fidelity: PromptFidelity;
} | undefined;
export declare function recordStagePrepared(opts: {
    root: string;
    preparation: StagePreparation;
    reused?: boolean;
}): void;
export declare function recordStageCompleted(opts: {
    root: string;
    preparation: StagePreparation;
    ok: boolean;
    failures: string[];
    idempotentReplay?: boolean;
    priorNodeStatuses?: Record<string, string>;
    state?: AgentState;
    durationMs?: number;
    agentUsage?: {
        inputTokens?: number;
        outputTokens?: number;
        measured: boolean;
    };
}): void;
export declare function recordToolCompleted(opts: {
    root: string;
    nodeId: string;
    receipt: ToolExecutionReceipt;
    iteration?: number;
    priorNodeStatuses?: Record<string, string>;
    state?: AgentState;
}): void;
export declare function recordStageInvalidated(opts: {
    root: string;
    preparation: Pick<StagePreparation, "id" | "nodeId" | "attempt" | "status" | "invalidationReason">;
    result?: "invalidated" | "canceled";
}): void;
/** Conservative inspection. Never treats prose as proof that a tool ran. */
export declare function inspectCursorExport(text: string): CursorExportInspection;
export declare function attachCursorExport(opts: {
    root: string;
    file: string;
    preparationIds?: string[];
    traceId?: string;
}): CursorExportRecord;
export declare function buildTraceSummary(root: string, traceId: string): TraceSummary;
export declare function renderTraceSummaryMarkdown(summary: TraceSummary): string;
export declare function writeSummaryFiles(root: string, traceId: string): TraceSummary;
export declare function cleanupTrace(root: string, traceId: string): {
    traceId: string;
    removed: string;
};
export declare function formatTraceStatus(root: string): string;
/**
 * Handle exclusive go/trace commands before the workflow lock and state save.
 * `--trace-start` with a workflow action is not exclusive: the caller starts then continues.
 */
export declare function dispatchTraceCli(opts: {
    root: string;
    kernel: string;
    graph: SkillGraph;
    argv: string[];
    log?: (message: string) => void;
}): TraceCliResult;
export declare function maybeStartTraceFromArgv(opts: {
    root: string;
    kernel: string;
    graph: SkillGraph;
    argv: string[];
    log?: (message: string) => void;
}): string | undefined;