ai-foreman 1.7.11 → 1.7.13

package/dist/observability.d.ts

@@ -0,0 +1,248 @@
+import type { ConfigurableAgentRole, DiagnosticSourceResultV1, ManagerRunSummaryV1, RunCurrentStateV1, RunRollupV1, RunSpanV1 } from "rafi-spec";
+export declare const OBSERVABILITY_DB_FILE = ".rafi/observability.sqlite3";
+export declare const OBSERVABILITY_SCHEMA_VERSION: 2;
+export interface ObservabilityConfig {
+    enabled: boolean;
+    sample_interval_seconds: number;
+    detail_retention_days: number;
+    log_retention_days: number;
+    detail_soft_limit_mb: number;
+    detail_hard_limit_mb: number;
+    log_limit_mb: number;
+}
+export declare const DEFAULT_OBSERVABILITY_CONFIG: ObservabilityConfig;
+export interface ObservationContext {
+    runId: string;
+    executionId?: string;
+    parentSpanId?: string;
+    providerTurnId?: string;
+    ticketId?: string;
+    deliveryUnitId?: string;
+    role?: ConfigurableAgentRole | "host";
+    stream?: string;
+    providerSessionId?: string;
+}
+export interface StartSpanInput extends Partial<Omit<RunSpanV1, "version" | "spanId" | "runId" | "startedAt" | "completionKnown">> {
+    spanId?: string;
+    kind: string;
+    name: string;
+    attributes?: Record<string, unknown>;
+}
+export interface FinishSpanInput {
+    outcome?: string;
+    completionKnown?: boolean;
+    attributes?: Record<string, unknown>;
+}
+export interface ObservabilityStoreOptions {
+    path?: string;
+    config?: Partial<ObservabilityConfig>;
+    now?: () => Date;
+    monotonicNow?: () => number;
+    ensureIgnore?: boolean;
+}
+export interface ManagerSessionRecord {
+    sessionId: string;
+    runId: string;
+    provider?: string;
+    startedAt: string;
+    endedAt?: string;
+    outcome?: string;
+    reportDigest?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    costUsd?: number;
+    errorCode?: string;
+    scope?: "project";
+    latestFocusRunId?: string;
+    projectReportDigest?: string;
+    lookupRounds?: number;
+    lookupOperations?: number;
+}
+/**
+ * Bounded, failure-isolated writer for diagnostic data. Recovery never depends on
+ * this database. Boundary records are synchronous; high-rate state and samples
+ * are coalesced by primary key and minute bucket.
+ */
+export declare class ObservabilityStore {
+    readonly path: string;
+    readonly config: ObservabilityConfig;
+    private readonly db;
+    private readonly projectDir;
+    private readonly now;
+    private readonly monotonicNow;
+    private readonly openMonotonic;
+    private disabled;
+    private warned;
+    private summaryOnly;
+    private priorCpu?;
+    constructor(projectDir: string, options?: ObservabilityStoreOptions);
+    close(): void;
+    isDisabled(): boolean;
+    isSummaryOnly(): boolean;
+    recordCapabilities(runId: string, capabilities: Record<string, DiagnosticSourceResultV1>, rafiVersion?: string): void;
+    beginExecution(input: {
+        runId: string;
+        executionId?: string;
+        leaseGeneration?: number;
+        pid?: number;
+        host?: string;
+        processStart?: string;
+    }): string;
+    endExecution(executionId: string, outcome: string): void;
+    attachExecutionLease(executionId: string, leaseGeneration: number | undefined): void;
+    abandonPriorExecutionSpans(runId: string, executionId: string): void;
+    startSpan(context: ObservationContext, input: StartSpanInput): string;
+    finishSpan(spanId: string, input?: FinishSpanInput): void;
+    recordEvent(context: ObservationContext, kind: string, input?: {
+        eventId?: string;
+        spanId?: string;
+        severity?: string;
+        attributes?: Record<string, unknown>;
+    }): string;
+    updateCurrentState(state: Omit<RunCurrentStateV1, "version" | "updatedAt"> & {
+        updatedAt?: string;
+    }): void;
+    recordMetric(context: ObservationContext, metric: string, value: number, input?: {
+        unit?: string;
+        boundary?: boolean;
+        attributes?: Record<string, unknown>;
+    }): void;
+    sampleProcess(context: ObservationContext, eventLoopDelayMs?: number, boundary?: boolean): void;
+    upsertRollup(rollup: RunRollupV1): void;
+    upsertRunSummary(summary: ManagerRunSummaryV1): void;
+    finalizeRun(runId: string, input: {
+        status: string;
+        branchMode?: string;
+        qaEnabled?: boolean;
+        primaryProvider?: "claude" | "codex";
+        model?: string;
+        ticketCount?: number;
+        ticketIds?: string[];
+        deliveryUnit?: string;
+        checkpoint?: string;
+        failureCategory?: string;
+        ticketSizeBucket?: string;
+        createdAt?: string;
+        updatedAt?: string;
+        completedAt?: string;
+        git?: ManagerRunSummaryV1["git"];
+    }): RunRollupV1 | undefined;
+    recordManagerSession(input: ManagerSessionRecord): void;
+    indexLogFile(path: string, runId: string): void;
+    closeLogFile(path: string, status: string): void;
+    maintainLogs(projectDir: string): {
+        compressed: number;
+        deleted: number;
+        reclaimedBytes: number;
+    };
+    enforceLimits(protectedRunIds?: readonly string[]): {
+        summaryOnly: boolean;
+        prunedRows: number;
+    };
+    checkpoint(): void;
+    compact(): void;
+    private meta;
+    private setMeta;
+    private guard;
+    private migrate;
+    private backfillBuildSnapshots;
+}
+/** Strictly read-only access. Construction never creates directories, journals, migrations, or ignore entries. */
+export declare class ObservabilityReader {
+    readonly path: string;
+    private readonly db?;
+    constructor(projectDir: string, path?: string);
+    close(): void;
+    available(): boolean;
+    schemaVersion(): number | undefined;
+    currentState(runId: string): RunCurrentStateV1[];
+    spans(runId: string): RunSpanV1[];
+    executions(runId: string): Array<{
+        executionId: string;
+        startedAt: string;
+        endedAt?: string;
+        outcome?: string;
+        leaseGeneration?: number;
+    }>;
+    rollups(): RunRollupV1[];
+    runSummaries(input?: {
+        runIds?: readonly string[];
+        statuses?: readonly string[];
+        providers?: readonly string[];
+        models?: readonly string[];
+        branchModes?: readonly string[];
+        qaEnabled?: boolean;
+        ticketIds?: readonly string[];
+        createdFrom?: string;
+        createdTo?: string;
+        completedFrom?: string;
+        completedTo?: string;
+        detailLevels?: readonly string[];
+        limit?: number;
+        offset?: number;
+    }): ManagerRunSummaryV1[];
+    phaseRollups(runIds: readonly string[]): Array<{
+        runId: string;
+        phase: string;
+        role: string;
+        ticketId: string;
+        durationMs: number;
+        count: number;
+    }>;
+    boundedSpans(runIds: readonly string[], perRunLimit?: number): Record<string, RunSpanV1[]>;
+    boundedEvidence(runIds: readonly string[], perRunLimit?: number): Record<string, {
+        spans: RunSpanV1[];
+        events: Array<{
+            eventId: string;
+            kind: string;
+            severity?: string;
+            observedAt: string;
+            attributes?: unknown;
+        }>;
+        metrics: Array<{
+            metric: string;
+            value: number;
+            unit?: string;
+            observedAt: string;
+        }>;
+        currentState: RunCurrentStateV1[];
+        executions: ReturnType<ObservabilityReader["executions"]>;
+    }>;
+    capability(runId: string): {
+        rafiVersion?: string;
+        sources: Record<string, DiagnosticSourceResultV1>;
+    } | undefined;
+    storage(): {
+        databaseBytes: number;
+        walBytes: number;
+        summaryOnly: boolean;
+    };
+}
+/** Records Manager session accounting only when observability already exists. It never creates or migrates schema. */
+export declare class ManagerSessionRecorder {
+    private readonly db?;
+    private readonly v2;
+    constructor(projectDir: string, path?: string);
+    close(): void;
+    record(input: ManagerSessionRecord): void;
+}
+/** One observer is owned by one build process attachment. */
+export declare class RunObserver {
+    readonly store: ObservabilityStore;
+    readonly runId: string;
+    readonly executionId: string;
+    private readonly storage;
+    private resourceTimer?;
+    constructor(store: ObservabilityStore, runId: string, input?: {
+        executionId?: string;
+        leaseGeneration?: number;
+    });
+    context(): ObservationContext;
+    withContext<T>(values: Partial<ObservationContext>, fn: () => T): T;
+    span<T>(kind: string, name: string, fn: () => Promise<T> | T, attributes?: Record<string, unknown>): Promise<T>;
+    signal(semantic?: boolean): void;
+    startResourceSampling(): void;
+    finish(outcome: string, metadata?: Omit<Parameters<ObservabilityStore["finalizeRun"]>[1], "status">): void;
+}
+export declare function sanitizeDiagnosticValue(value: unknown): unknown;
+export declare function diagnosticDigest(value: unknown): string;