@mrace07/kairo 0.1.0

package/dist/domain/models.d.ts

@@ -0,0 +1,247 @@
+export type Role = "user" | "model" | "tool";
+export type ProviderId = "gemini" | "groq" | "mistral";
+/** Credential-only services are deliberately separate from selectable coding providers. */
+export type CredentialId = ProviderId | "jev";
+export interface ModelSelection {
+    provider: ProviderId;
+    model: string;
+}
+/** Metadata-only events avoid copying source code, credentials, or command output into traces. */
+export interface TaskEvent {
+    id?: number;
+    taskId: string;
+    kind: "status" | "model_started" | "provider_retry" | "provider_retry_wait" | "provider_exhausted" | "model_finished" | "tool_requested" | "tool_started" | "tool_finished" | "approval" | "autonomous" | "repair" | "verification" | "verification_selected" | "plan_submitted" | "jev_requested" | "jev_completed" | "jev_failed";
+    createdAt: number;
+    operationId?: string;
+    name?: string;
+    outcome?: string;
+    durationMs?: number;
+    exitCode?: number | null;
+}
+export interface Message {
+    role: Role;
+    content: string;
+    createdAt: number;
+    toolCallId?: string;
+    toolName?: string;
+}
+export interface ToolCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+export interface ModelTurn {
+    text: string;
+    toolCalls: ToolCall[];
+}
+export interface ToolResult {
+    ok: boolean;
+    output: string;
+    exitCode?: number | null;
+    durationMs?: number;
+}
+export interface VerificationCandidate {
+    label: "test" | "typecheck" | "lint" | "build";
+    command: string;
+    /** Discovery metadata explains a recommendation without retaining source or output. */
+    scope?: "focused" | "broad";
+    reason?: string;
+    evidence?: RepositoryEvidence[];
+}
+/** Records why one safe verification command was selected for a task. */
+export interface VerificationSelection {
+    command: string;
+    label: VerificationCandidate["label"] | "custom";
+    scope: "focused" | "broad";
+    reason: string;
+    source: "recommended" | "model" | "manual" | "repair";
+}
+export interface RepositoryFile {
+    path: string;
+    terms: string[];
+    symbols: string[];
+    imports: string[];
+    relatedFiles: string[];
+}
+export type RepositoryFileKind = "instruction" | "manifest" | "ci" | "build" | "documentation" | "source" | "test" | "config" | "other";
+export interface RepositoryEntry {
+    path: string;
+    kind: RepositoryFileKind;
+    size: number;
+    mtimeMs: number;
+    contentHash?: string;
+}
+export interface RepositoryFingerprint {
+    value: string;
+    kind: "git" | "filesystem";
+    gitRoot?: string;
+    branch?: string;
+    head?: string;
+}
+export interface RepositoryEvidence {
+    path: string;
+    kind: "manifest" | "lockfile" | "config" | "ci" | "build";
+}
+export interface RepositorySnapshot {
+    schemaVersion: 1;
+    root: string;
+    fingerprint: RepositoryFingerprint;
+    entries: RepositoryEntry[];
+    ecosystems: string[];
+    changedPaths: string[];
+    instructionFiles: string[];
+    documentationFiles: string[];
+    manifestFiles: string[];
+    ciFiles: string[];
+    buildFiles: string[];
+    truncated: boolean;
+    packageName?: string;
+    packageManager: "npm" | "pnpm" | "yarn" | "bun" | "unknown";
+    scripts: Record<string, string>;
+    configFiles: string[];
+    sourceRoots: string[];
+    testRoots: string[];
+    ignoredPaths: string[];
+    indexedFiles: string[];
+    files: RepositoryFile[];
+    verificationCandidates: VerificationCandidate[];
+    createdAt: number;
+}
+export interface FailureEvidence {
+    summary: string;
+    fileLocations: Array<{
+        path: string;
+        line?: number;
+        column?: number;
+    }>;
+    excerpts: string[];
+}
+export interface RepairAttempt {
+    id: string;
+    taskId: string;
+    command: string;
+    evidence: FailureEvidence;
+    selectedFiles: string[];
+    createdAt: number;
+}
+export type TaskStatus = "planning" | "acting" | "verifying" | "planned" | "completed" | "verification_required" | "failed" | "interrupted" | "cancelled";
+export type TaskMode = "implementation" | "planning";
+/** A reviewable, execution-free proposal produced by Kairo's planning mode. */
+export interface TaskPlan {
+    goal: string;
+    assumptions: string[];
+    files: Array<{
+        path: string;
+        reason: string;
+    }>;
+    steps: string[];
+    verification: {
+        command?: string;
+        reason: string;
+    };
+    risks: string[];
+}
+export interface Task {
+    id: string;
+    sessionId: string;
+    prompt: string;
+    mode: TaskMode;
+    status: TaskStatus;
+    plan?: TaskPlan;
+    changedFiles: string[];
+    /** User-approved write paths, scoped to this task and never applied to commands. */
+    approvedWritePaths: string[];
+    verificationCommand?: string;
+    verificationOutput?: string;
+    verificationPassed?: boolean;
+    verificationExitCode?: number | null;
+    verificationDiscovered?: boolean;
+    verificationSelection?: VerificationSelection;
+    summary?: string;
+    error?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface ContextCheckpoint {
+    id: string;
+    sessionId: string;
+    taskId?: string;
+    summary: string;
+    throughMessageId: number;
+    createdAt: number;
+}
+/** One benchmark result combines the task outcome, an independent verifier, and agent metrics. */
+export interface EvaluationResult {
+    failureCategory?: EvaluationAttempt["failureCategory"];
+    id: string;
+    passed: boolean;
+    taskStatus: TaskStatus;
+    verified: boolean;
+    expectationPassed: boolean;
+    error?: string;
+    metrics: {
+        providerRetries?: number;
+        providerWaitMs?: number;
+        modelTurns: number;
+        toolExecutions: number;
+        toolFailures: number;
+        approvals: number;
+        repairs: number;
+        verificationPasses: number;
+        verificationFailures: number;
+        verificationSelections: number;
+        focusedVerifications: number;
+        broadVerifications: number;
+        repairConverged: boolean;
+        modelMs: number;
+        toolMs: number;
+        jevDecisions?: number;
+        jevFailures?: number;
+        jevMs?: number;
+        jevRoutes?: number;
+        jevSafetyChecks?: number;
+        jevRecoveryChecks?: number;
+    };
+}
+/** A DeepEval verdict is advisory model-quality evidence, alongside deterministic task checks. */
+export interface DeepEvalVerdict {
+    passed: boolean;
+    score?: number;
+    reason?: string;
+    error?: string;
+}
+/** A live evaluation combines isolated workspace assertions with an LLM-judged agent trace. */
+export interface LiveEvaluationResult extends EvaluationResult {
+    judge: DeepEvalVerdict;
+}
+/** One live run of a Kairo-on-Kairo benchmark task. */
+export interface SelfEvaluationResult extends EvaluationResult {
+    trial: number;
+}
+/** Durable metadata for one real-model reliability-suite run. */
+export interface EvaluationRun {
+    id: string;
+    suite: "self";
+    provider: ProviderId;
+    model: string;
+    sourceRevision: string;
+    trialCount: number;
+    attemptCount: number;
+    passedCount: number;
+    startedAt: number;
+    completedAt?: number;
+}
+/** Sanitized attempt data retained for reliability comparisons, never raw agent content. */
+export interface EvaluationAttempt {
+    runId: string;
+    scenarioId: string;
+    trial: number;
+    passed: boolean;
+    taskStatus: TaskStatus;
+    verified: boolean;
+    expectationPassed: boolean;
+    failureCategory?: "agent" | "verification" | "grader" | "setup" | "unknown" | import("./provider-error.js").ProviderFailure;
+    metrics: EvaluationResult["metrics"];
+    durationMs: number;
+    createdAt: number;
+}

package/dist/domain/models.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/ports.d.ts

@@ -0,0 +1,87 @@
+import type { ContextCheckpoint, Message, ModelTurn, Task, ToolCall, ToolResult, RepairAttempt, TaskEvent, EvaluationAttempt, EvaluationRun, CredentialId, TaskMode } from "./models.js";
+export interface ModelProvider {
+    stream(messages: Message[], onText: (chunk: string) => void, onProgress?: (event: import("./provider-error.js").ProviderProgress) => void, systemInstruction?: string, toolsEnabled?: boolean): Promise<ModelTurn>;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    mutating: boolean;
+}
+export interface ToolExecutor {
+    readonly root: string;
+    description(call: ToolCall): string;
+    execute(call: ToolCall): Promise<ToolResult>;
+}
+export interface TaskStore {
+    /** Appends metadata for one observable task operation. */
+    recordTaskEvent(event: TaskEvent): void;
+    /** Returns events in durable insertion order, including earlier resumed runs. */
+    taskEvents(taskId: string): TaskEvent[];
+    messages(sessionId: string): Message[];
+    recentMessages(sessionId: string, limit: number): Message[];
+    addMessage(sessionId: string, message: Message): void;
+    recordTool(sessionId: string, id: string, name: string, args: Record<string, unknown>, approved: boolean | null, output: string): void;
+    startTask(sessionId: string, prompt: string, mode?: TaskMode): Task;
+    task(id: string): Task | undefined;
+    latestTask(sessionId: string): Task | undefined;
+    updateTask(id: string, patch: Partial<Pick<Task, "status" | "mode" | "plan" | "changedFiles" | "approvedWritePaths" | "verificationCommand" | "verificationOutput" | "verificationPassed" | "verificationExitCode" | "verificationDiscovered" | "verificationSelection" | "summary" | "error">>): Task;
+    saveCheckpoint(sessionId: string, taskId: string | undefined, summary: string, throughMessageId: number): ContextCheckpoint;
+    latestCheckpoint(sessionId: string): ContextCheckpoint | undefined;
+    messageCount(sessionId: string): number;
+    lastMessageId(sessionId: string): number;
+    saveRepositorySnapshot(sessionId: string, snapshot: import("./models.js").RepositorySnapshot): void;
+    repositorySnapshot(sessionId: string): import("./models.js").RepositorySnapshot | undefined;
+    recordRepairAttempt(attempt: RepairAttempt): void;
+    repairAttempts(taskId: string): RepairAttempt[];
+}
+export interface ApprovalPolicy {
+    approve(call: ToolCall, description: string): Promise<ApprovalDecision>;
+}
+/** `task_file` authorizes later writes only to the same normalized path in the current task. */
+export type ApprovalDecision = boolean | "task_file";
+export interface CredentialStore {
+    get(provider: CredentialId): Promise<string | undefined>;
+    save(provider: CredentialId, value: string): Promise<void>;
+    clear(provider: CredentialId): Promise<void>;
+}
+export type JevRisk = "low" | "medium" | "high";
+export type JevRoute = "build" | "plan";
+export type JevRecovery = "repair" | "broaden" | "escalate";
+export type JevModelTier = "fast" | "balanced" | "strong";
+export type JevInteractionIntent = "conversation" | "answer" | "repository_task";
+export interface JevDecision<T extends string> {
+    value: T;
+    confidence: number;
+}
+export interface JevAssessment {
+    risk: JevRisk;
+    confidence: number;
+}
+/** Classifies bounded operation metadata; Kairo applies all autonomy policy locally. */
+export interface JevSafetyAdvisor {
+    assess(state: string): Promise<JevAssessment>;
+    /** Routes an input before Kairo creates a repository task or exposes tools. */
+    intent?(state: string): Promise<JevDecision<JevInteractionIntent>>;
+    route(state: string): Promise<JevDecision<JevRoute>>;
+    recover(state: string): Promise<JevDecision<JevRecovery>>;
+    modelTier(state: string): Promise<JevDecision<JevModelTier>>;
+}
+export interface JevFeatures {
+    routing: boolean;
+    safety: boolean;
+    recovery: boolean;
+    /** Allows only Jev-approved, discovered verification commands to run without a prompt. */
+    autonomy?: boolean;
+}
+/** Stores metadata-only reliability evidence separately from raw task history. */
+export interface EvaluationStore {
+    setEvaluationBaseline(runId: string): EvaluationRun;
+    evaluationBaseline(): EvaluationRun | undefined;
+    createEvaluationRun(input: Omit<EvaluationRun, "id" | "attemptCount" | "passedCount">): EvaluationRun;
+    saveEvaluationAttempt(attempt: EvaluationAttempt): void;
+    completeEvaluationRun(id: string): EvaluationRun;
+    evaluationRuns(limit?: number): EvaluationRun[];
+    evaluationRun(id: string): EvaluationRun | undefined;
+    evaluationAttempts(runId: string): EvaluationAttempt[];
+}

package/dist/domain/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/provider-error.d.ts

@@ -0,0 +1,18 @@
+export type ProviderFailure = "quota" | "authentication" | "network" | "service" | "request";
+export interface ProviderProgress {
+    kind: "retry" | "retry_wait" | "exhausted";
+    category: ProviderFailure;
+    retry: number;
+    delayMs: number;
+}
+/** Exposes only safe provider metadata; never retains the underlying error body. */
+export declare class ProviderError extends Error {
+    readonly category: ProviderFailure;
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number | undefined;
+    /** A deliberately generic next step; never copied from a provider response. */
+    readonly guidance?: string | undefined;
+    constructor(category: ProviderFailure, retryable: boolean, retryAfterMs?: number | undefined, provider?: string, 
+    /** A deliberately generic next step; never copied from a provider response. */
+    guidance?: string | undefined);
+}

package/dist/domain/provider-error.js

@@ -0,0 +1,17 @@
+/** Exposes only safe provider metadata; never retains the underlying error body. */
+export class ProviderError extends Error {
+    category;
+    retryable;
+    retryAfterMs;
+    guidance;
+    constructor(category, retryable, retryAfterMs, provider = "Model provider", 
+    /** A deliberately generic next step; never copied from a provider response. */
+    guidance) {
+        super(`${provider} request failed (${category}).${guidance ? ` ${guidance}` : ""}`);
+        this.category = category;
+        this.retryable = retryable;
+        this.retryAfterMs = retryAfterMs;
+        this.guidance = guidance;
+        this.name = "ProviderError";
+    }
+}

package/dist/infrastructure/configuration/config.d.ts

@@ -0,0 +1,24 @@
+import type { ModelSelection } from "../../domain/models.js";
+export interface KairoConfig extends ModelSelection {
+    jevEnabled: boolean;
+    jevRoutingEnabled: boolean;
+    jevSafetyEnabled: boolean;
+    jevRecoveryEnabled: boolean;
+    jevAutonomyEnabled: boolean;
+    autoModelRoutingEnabled: boolean;
+}
+export declare const defaultConfig: KairoConfig;
+/** Reads only an explicitly stored, valid config; legacy model-only files migrate to Gemini. */
+export declare function loadStoredConfig(): Promise<KairoConfig | undefined>;
+/** Loads the user configuration, falling back to safe defaults when it is absent. */
+export declare function loadConfig(): Promise<KairoConfig>;
+/** Persists an atomic provider/model selection without storing credentials. */
+export declare function setModelSelection(selection: ModelSelection): Promise<void>;
+/** Persists Jev's enabled flag while its secret remains only in Keychain. */
+export declare function setJevEnabled(jevEnabled: boolean): Promise<void>;
+/** Updates one Jev capability without exposing its credential in configuration. */
+export declare function setJevFeature(feature: "routing" | "safety" | "recovery" | "autonomy", enabled: boolean): Promise<void>;
+/** Persists whether Jev may choose an allowed coding model for each BUILD request. */
+export declare function setAutoModelRoutingEnabled(enabled: boolean): Promise<void>;
+/** Updates one supported configuration value while preserving all other settings. */
+export declare function setConfig(key: string, value: string): Promise<void>;

package/dist/infrastructure/configuration/config.js

@@ -0,0 +1,79 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { configPath, ensureStateDir } from "../filesystem/platform-paths.js";
+import { isProviderId } from "../providers/provider-registry.js";
+export const defaultConfig = {
+    provider: "gemini",
+    model: "gemini-2.5-flash",
+    jevEnabled: false,
+    jevRoutingEnabled: true,
+    jevSafetyEnabled: true,
+    jevRecoveryEnabled: true,
+    jevAutonomyEnabled: false,
+    autoModelRoutingEnabled: false,
+};
+/** Reads only an explicitly stored, valid config; legacy model-only files migrate to Gemini. */
+export async function loadStoredConfig() {
+    try {
+        const parsed = JSON.parse(await readFile(configPath(), "utf8"));
+        if (typeof parsed.model !== "string" || !parsed.model.trim())
+            return undefined;
+        return {
+            provider: isProviderId(parsed.provider) ? parsed.provider : "gemini",
+            model: parsed.model.trim(),
+            jevEnabled: parsed.jevEnabled === true,
+            jevRoutingEnabled: parsed.jevRoutingEnabled !== false,
+            jevSafetyEnabled: parsed.jevSafetyEnabled !== false,
+            jevRecoveryEnabled: parsed.jevRecoveryEnabled !== false,
+            jevAutonomyEnabled: parsed.jevAutonomyEnabled === true,
+            autoModelRoutingEnabled: parsed.autoModelRoutingEnabled === true,
+        };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw new Error(`Could not read Kairo config: ${error.message}`);
+    }
+}
+/** Loads the user configuration, falling back to safe defaults when it is absent. */
+export async function loadConfig() {
+    return (await loadStoredConfig()) ?? { ...defaultConfig };
+}
+/** Persists an atomic provider/model selection without storing credentials. */
+export async function setModelSelection(selection) {
+    if (!isProviderId(selection.provider) || !selection.model.trim())
+        throw new Error("A supported provider and non-empty model are required.");
+    await ensureStateDir();
+    const current = await loadConfig();
+    await saveConfig({ ...current, provider: selection.provider, model: selection.model.trim() });
+}
+/** Persists Jev's enabled flag while its secret remains only in Keychain. */
+export async function setJevEnabled(jevEnabled) {
+    await saveConfig({ ...(await loadConfig()), jevEnabled });
+}
+/** Updates one Jev capability without exposing its credential in configuration. */
+export async function setJevFeature(feature, enabled) {
+    const key = feature === "routing"
+        ? "jevRoutingEnabled"
+        : feature === "safety"
+            ? "jevSafetyEnabled"
+            : feature === "recovery"
+                ? "jevRecoveryEnabled"
+                : "jevAutonomyEnabled";
+    await saveConfig({ ...(await loadConfig()), [key]: enabled });
+}
+/** Persists whether Jev may choose an allowed coding model for each BUILD request. */
+export async function setAutoModelRoutingEnabled(enabled) {
+    await saveConfig({ ...(await loadConfig()), autoModelRoutingEnabled: enabled });
+}
+async function saveConfig(config) {
+    await ensureStateDir();
+    await writeFile(configPath(), `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}
+/** Updates one supported configuration value while preserving all other settings. */
+export async function setConfig(key, value) {
+    if (key !== "model" || !value.trim())
+        throw new Error("Only a non-empty `model` setting is supported.");
+    const config = await loadConfig();
+    config.model = value.trim();
+    await setModelSelection(config);
+}

package/dist/infrastructure/filesystem/platform-paths.d.ts

@@ -0,0 +1,8 @@
+/** Returns Kairo's overridable platform state directory. */
+export declare function stateDir(): string;
+/** Creates the state directory before SQLite or configuration writes use it. */
+export declare function ensureStateDir(): Promise<string>;
+/** Returns the configuration-file path inside Kairo's platform state directory. */
+export declare const configPath: () => string;
+/** Returns the SQLite database path inside Kairo's platform state directory. */
+export declare const databasePath: () => string;

package/dist/infrastructure/filesystem/platform-paths.js

@@ -0,0 +1,18 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdir } from "node:fs/promises";
+/** Returns Kairo's overridable platform state directory. */
+export function stateDir() {
+    return (process.env.KAIRO_STATE_DIR ||
+        join(process.env.XDG_STATE_HOME || join(homedir(), ".local", "state"), "kairo"));
+}
+/** Creates the state directory before SQLite or configuration writes use it. */
+export async function ensureStateDir() {
+    const dir = stateDir();
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+/** Returns the configuration-file path inside Kairo's platform state directory. */
+export const configPath = () => join(stateDir(), "config.json");
+/** Returns the SQLite database path inside Kairo's platform state directory. */
+export const databasePath = () => join(stateDir(), "sessions.sqlite");

package/dist/infrastructure/persistence/sqlite-session-store.d.ts

@@ -0,0 +1,82 @@
+import type { ContextCheckpoint, Message, TaskEvent, RepairAttempt, RepositorySnapshot, Task, TaskMode, EvaluationAttempt, EvaluationRun } from "../../domain/models.js";
+export interface Session {
+    id: string;
+    workspace: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export declare class SqliteSessionStore {
+    private readonly db;
+    /** Wraps an already-initialized database; callers use open() to guarantee setup. */
+    private constructor();
+    /** Opens the database, creates current schema objects, and recovers interrupted tasks. */
+    static open(path?: string): Promise<SqliteSessionStore>;
+    /** Closes the SQLite handle after the CLI session exits. */
+    close(): void;
+    /** Atomically replaces the local self baseline after validating the selected run. */
+    setEvaluationBaseline(runId: string): EvaluationRun;
+    /** Resolves the baseline pointer without duplicating evaluation metadata. */
+    evaluationBaseline(): EvaluationRun | undefined;
+    /** Starts a metadata-only real-model evaluation run. */
+    createEvaluationRun(input: Omit<EvaluationRun, "id" | "attemptCount" | "passedCount">): EvaluationRun;
+    /** Saves counters and a sanitized outcome without raw prompts, source, or tool output. */
+    saveEvaluationAttempt(attempt: EvaluationAttempt): void;
+    /** Computes aggregate counts from attempts so historical reports cannot drift. */
+    completeEvaluationRun(id: string): EvaluationRun;
+    /** Lists recent evaluation runs, newest first. */
+    evaluationRuns(limit?: number): EvaluationRun[];
+    /** Reads one saved evaluation run. */
+    evaluationRun(id: string): EvaluationRun | undefined;
+    /** Reads attempts in stable execution order. */
+    evaluationAttempts(runId: string): EvaluationAttempt[];
+    /** Stores bounded operation metadata separately from model context and raw tool history. */
+    recordTaskEvent(event: TaskEvent): void;
+    /** Uses insertion ids rather than timestamps to preserve ordering within the same millisecond. */
+    taskEvents(taskId: string): TaskEvent[];
+    /** Creates a durable session associated with one resolved workspace. */
+    create(workspace: string): Session;
+    /** Loads one session by id, if it still exists. */
+    get(id: string): Session | undefined;
+    /** Lists sessions from most recently active to oldest. */
+    list(): Session[];
+    /** Loads all messages required to reconstruct a full conversation. */
+    messages(sessionId: string): Message[];
+    /** Loads only the newest messages for bounded model context. */
+    recentMessages(sessionId: string, limit: number): Message[];
+    /** Appends one durable message and refreshes the owning session timestamp. */
+    addMessage(sessionId: string, message: Message): void;
+    /** Records the requested action, approval decision, and visible tool output. */
+    recordTool(sessionId: string, id: string, name: string, args: Record<string, unknown>, approved: boolean | null, output: string): void;
+    /** Creates a new task in the initial planning state. */
+    startTask(sessionId: string, prompt: string, mode?: TaskMode): Task;
+    /** Loads one task by id and maps database columns to domain names. */
+    task(id: string): Task | undefined;
+    /** Finds the newest task belonging to a session. */
+    latestTask(sessionId: string): Task | undefined;
+    /** Finds the most recently saved planning artifact in a session. */
+    latestPlan(sessionId: string): Task | undefined;
+    /** Merges a partial task update and writes the complete task state atomically. */
+    updateTask(id: string, patch: Partial<Pick<Task, "status" | "mode" | "plan" | "changedFiles" | "approvedWritePaths" | "verificationCommand" | "verificationOutput" | "verificationPassed" | "verificationExitCode" | "verificationDiscovered" | "verificationSelection" | "summary" | "error">>): Task;
+    /** Persists a summary that replaces older conversation detail in future context. */
+    saveCheckpoint(sessionId: string, taskId: string | undefined, summary: string, throughMessageId: number): ContextCheckpoint;
+    /** Retrieves the most recent compaction checkpoint for a session. */
+    latestCheckpoint(sessionId: string): ContextCheckpoint | undefined;
+    /** Counts messages to decide when automatic compaction is needed. */
+    messageCount(sessionId: string): number;
+    /** Returns the newest message id used to mark checkpoint coverage. */
+    lastMessageId(sessionId: string): number;
+    /** Upserts the session's bounded, derived repository snapshot. */
+    saveRepositorySnapshot(sessionId: string, snapshot: RepositorySnapshot): void;
+    /** Reads current snapshots and normalizes legacy profiles as stale snapshots. */
+    repositorySnapshot(sessionId: string): RepositorySnapshot | undefined;
+    /** Persists one verification failure that started an agent repair cycle. */
+    recordRepairAttempt(attempt: RepairAttempt): void;
+    /** Returns repair attempts in the order they happened for context and evaluation. */
+    repairAttempts(taskId: string): RepairAttempt[];
+    /** Marks tasks left active by a process exit so the user can explicitly resume them. */
+    private recoverInterruptedTasks;
+    /** Converts a raw SQLite row into the application's Task object. */
+    private toTask;
+    /** Converts one evaluation run row while keeping persistence column names private. */
+    private toEvaluationRun;
+}