om-memory-system 3.4.0-next.23 → 3.4.0-next.26

package/dist/importer/auto-backfill.js

@@ -1,9 +1,11 @@
 import { CONFIG, refreshConfigIfChanged } from "../config.js";
 import { log } from "../services/logger.js";
 import { tryAcquireBackfillLock } from "./backfill-lock.js";
-import { getBackfillCutoff, updateBackfillStatus, } from "../services/backfill-state.js";
+import { getBackfillCutoff, recordUnresolvedDirectories, unresolvedDirectoriesOf, updateBackfillStatus, } from "../services/backfill-state.js";
 import { runHistoryImport, } from "./run-import.js";
 import { isManualImportRunning } from "./manual-import-guard.js";
+import { isBackfillPaused } from "./import-runs.js";
+import { workProgress } from "./import-progress.js";
 const zero = () => ({ imported: 0, skipped: 0, failed: 0, pending: 0, unresolved: 0 });
 function counts(report) {
     return {
@@ -27,14 +29,19 @@ const delay = (signal) => new Promise((resolve) => {
 });
 /** Schedule one host's history import after startup; callers do not await it. */
 export async function scheduleAutoBackfill(options) {
-    await (options.wait ?? (() => delay(options.signal)))();
+    if (!options.userStarted)
+        await (options.wait ?? (() => delay(options.signal)))();
     if (options.signal?.aborted)
         return;
-    if (!(options.enabled ??
-        (() => CONFIG.autoBackfill && process.env.OMMS_DISABLE_AUTO_BACKFILL !== "1"))())
+    const enabled = options.enabled ??
+        (() => CONFIG.autoBackfill && process.env.OMMS_DISABLE_AUTO_BACKFILL !== "1");
+    if (!options.userStarted && !enabled())
         return;
     if (isManualImportRunning(options.host))
         return;
+    // A paused backfill waits for Resume, across host starts.
+    if (await isBackfillPaused(options.host).catch(() => false))
+        return;
     const release = await tryAcquireBackfillLock(options.host);
     if (!release)
         return;
@@ -72,6 +79,10 @@ export async function scheduleAutoBackfill(options) {
             signal: controller.signal,
         });
         current = counts(dry);
+        await recordUnresolvedDirectories(options.host, unresolvedDirectoriesOf(dry)).catch((error) => log("Backfill unresolved directories write failed", {
+            host: options.host,
+            error: error instanceof Error ? error.message : String(error),
+        }));
         if (controller.signal.aborted) {
             state = "stopped";
             return;
@@ -122,16 +133,22 @@ export async function scheduleAutoBackfill(options) {
             cwd: options.cwd,
             models,
             signal: controller.signal,
-            onProgress: (done, total) => {
-                processed = done;
+            track: {
+                surface: options.surface ?? "auto",
+                lockHeld: true,
+                expectedTotal: dry.unitsWouldImport,
+            },
+            onProgress: (done, total, _preview, alreadyHandled = 0) => {
+                // Count only units that needed work; ledger hits are not pending work.
+                processed = workProgress(done, total, alreadyHandled, dry.unitsWouldImport).done;
                 const now = clock();
                 if (now - checkedAt < 5_000)
                     return;
                 checkedAt = now;
                 refreshConfigIfChanged(options.cwd);
-                if (!CONFIG.autoBackfill)
+                if (!options.userStarted && !CONFIG.autoBackfill)
                     controller.abort();
-                current = { ...current, pending: Math.max(0, total - done) };
+                current = { ...current, pending: Math.max(0, dry.unitsWouldImport - processed) };
                 pendingWrite = pendingWrite
                     .then(() => updateBackfillStatus(options.host, { state: "running", model, counts: current }))
                     .catch((error) => {
@@ -143,8 +160,10 @@ export async function scheduleAutoBackfill(options) {
             },
         });
         await pendingWrite;
-        current = { ...counts(real), pending: Math.max(0, dry.unitsWouldImport - processed) };
-        state = controller.signal.aborted ? "stopped" : real.unitsFailed ? "failed" : "done";
+        const finished = real.unitsImported + real.unitsSkipped + real.unitsFailed;
+        current = { ...counts(real), pending: Math.max(0, dry.unitsWouldImport - finished) };
+        const paused = await isBackfillPaused(options.host).catch(() => false);
+        state = controller.signal.aborted || paused ? "stopped" : real.unitsFailed ? "failed" : "done";
         if (!options.signal?.aborted) {
             options.notify(`${options.host} automatic import ${state}: ${current.imported} imported, ${current.failed} failed. autoBackfill controls the next run.`);
         }

package/dist/importer/backfill-controls.d.ts

@@ -0,0 +1,37 @@
+import { type BackfillHost } from "./backfill-model.js";
+import { type ImportRun } from "./import-runs.js";
+import type { HistoryImportModels } from "./run-import.js";
+type ResolveModels = () => Promise<{
+    model: string;
+    models: HistoryImportModels;
+}>;
+export declare function registerHostBackfillModels(host: BackfillHost, resolve: ResolveModels): void;
+/** A control request the page cannot carry out; `status` is the HTTP status. */
+export declare class BackfillControlError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/** True when the host's backfill model is the external API, directly or through the live rule. */
+export declare function backfillUsesExternal(host: BackfillHost): boolean;
+/** Why Run now is not available for the host in this process, or null when it is. */
+export declare function runNowUnavailableReason(host: BackfillHost): string | null;
+export interface BackfillHostStatus {
+    run: ImportRun | null;
+    runNowUnavailable: string | null;
+}
+/** Run now, Pause, and Resume for each host's backfill, run in this process. */
+export declare class BackfillControls {
+    private readonly controllers;
+    status(): Promise<Record<BackfillHost, BackfillHostStatus>>;
+    runNow(host: BackfillHost, cwd: string): Promise<{
+        started: true;
+    }>;
+    /** Stop after the current exchange; a run in another process sees the flag at its next write. */
+    pause(host: BackfillHost): Promise<{
+        paused: true;
+    }>;
+    resume(host: BackfillHost, cwd: string): Promise<{
+        started: true;
+    }>;
+}
+export {};

package/dist/importer/backfill-controls.js

@@ -0,0 +1,119 @@
+import { CONFIG } from "../config.js";
+import { log } from "../services/logger.js";
+import { getAutoCaptureProviderStatus, resolvePiLiveModel, } from "../services/ai/live-model-choice.js";
+import { parseBackfillModel } from "./backfill-model.js";
+import { readImportRun, setBackfillPaused } from "./import-runs.js";
+/** A host runtime in this process that can resolve its signed-in backfill models. */
+const hostResolvers = new Map();
+export function registerHostBackfillModels(host, resolve) {
+    hostResolvers.set(host, resolve);
+}
+/** A control request the page cannot carry out; `status` is the HTTP status. */
+export class BackfillControlError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "BackfillControlError";
+    }
+}
+const label = (host) => (host === "pi" ? "Pi" : "OpenCode");
+/** True when the host's backfill model is the external API, directly or through the live rule. */
+export function backfillUsesExternal(host) {
+    const choice = parseBackfillModel(CONFIG, host);
+    if (choice === "external")
+        return true;
+    if (choice !== "inherit")
+        return false;
+    if (host === "pi")
+        return resolvePiLiveModel(CONFIG).kind === "manual";
+    const live = getAutoCaptureProviderStatus(CONFIG);
+    return live.ready && live.mode === "manual";
+}
+/** Why Run now is not available for the host in this process, or null when it is. */
+export function runNowUnavailableReason(host) {
+    if (hostResolvers.has(host))
+        return null;
+    if (!backfillUsesExternal(host)) {
+        return `Open ${label(host)}, or choose the external API for ${label(host)}'s backfill`;
+    }
+    return null;
+}
+async function resolveModels(host) {
+    const hostResolver = hostResolvers.get(host);
+    if (hostResolver && !backfillUsesExternal(host))
+        return hostResolver();
+    const { resolveExternalBackfillModels } = await import("./external-backfill-models.js");
+    return resolveExternalBackfillModels(host, CONFIG);
+}
+/** Run now, Pause, and Resume for each host's backfill, run in this process. */
+export class BackfillControls {
+    controllers = new Map();
+    async status() {
+        const entry = async (host) => ({
+            run: await readImportRun(host),
+            runNowUnavailable: runNowUnavailableReason(host),
+        });
+        return { pi: await entry("pi"), opencode: await entry("opencode") };
+    }
+    async runNow(host, cwd) {
+        const reason = runNowUnavailableReason(host);
+        if (reason)
+            throw new BackfillControlError(reason, 409);
+        const current = await readImportRun(host);
+        if (current?.state === "running" || this.controllers.has(host)) {
+            throw new BackfillControlError(`${host === "pi" ? "A" : "An"} ${label(host)} import is already running`, 409);
+        }
+        if (current?.paused) {
+            throw new BackfillControlError(`${label(host)}'s backfill is paused; resume it first`, 409);
+        }
+        // Fail fast with the missing setting instead of starting a run that cannot call a model.
+        if (backfillUsesExternal(host) || !hostResolvers.has(host)) {
+            const { externalModelIssues } = await import("../services/ai/live-model-choice.js");
+            const issues = externalModelIssues(CONFIG);
+            if (issues.length > 0)
+                throw new BackfillControlError(issues.join("; "), 409);
+        }
+        const controller = new AbortController();
+        this.controllers.set(host, controller);
+        const { scheduleAutoBackfill } = await import("./auto-backfill.js");
+        void scheduleAutoBackfill({
+            host,
+            cwd,
+            signal: controller.signal,
+            surface: "web",
+            userStarted: true,
+            resolveModels: () => resolveModels(host),
+            notify: (message) => log("Backfill from the Settings page", { host, message: message.slice(0, 200) }),
+        })
+            .catch((error) => log("Backfill from the Settings page failed", {
+            host,
+            error: error instanceof Error ? error.name : "unknown",
+        }))
+            .finally(() => {
+            if (this.controllers.get(host) === controller)
+                this.controllers.delete(host);
+        });
+        return { started: true };
+    }
+    /** Stop after the current exchange; a run in another process sees the flag at its next write. */
+    async pause(host) {
+        await setBackfillPaused(host, true);
+        this.controllers.get(host)?.abort();
+        return { paused: true };
+    }
+    async resume(host, cwd) {
+        const reason = runNowUnavailableReason(host);
+        if (reason)
+            throw new BackfillControlError(reason, 409);
+        await setBackfillPaused(host, false);
+        try {
+            return await this.runNow(host, cwd);
+        }
+        catch (error) {
+            // Run now refused (a run is active, or a setting is missing): stay paused.
+            await setBackfillPaused(host, true);
+            throw error;
+        }
+    }
+}

package/dist/importer/backfill-lock.d.ts

@@ -1,3 +1,4 @@
 import type { BackfillHost } from "./backfill-model.js";
+export declare function isProcessAlive(pid: number): boolean;
 /** Claim one host's import without holding a database transaction during the run. */
 export declare function tryAcquireBackfillLock(host: BackfillHost, storagePath?: string): Promise<(() => Promise<void>) | null>;

package/dist/importer/backfill-lock.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { CONFIG } from "../config.js";
 import { tursoConnectionManager } from "../services/turso/connection-manager.js";
-function live(pid) {
+export function isProcessAlive(pid) {
     if (!Number.isSafeInteger(pid) || pid <= 0)
         return false;
     try {
@@ -26,7 +26,7 @@ export async function tryAcquireBackfillLock(host, storagePath = CONFIG.storageP
             const holder = await db.get("SELECT pid, token FROM backfill_locks WHERE host = ?", [host]);
             if (!holder)
                 continue;
-            if (live(holder.pid))
+            if (isProcessAlive(holder.pid))
                 return null;
             const replaced = await db.run("UPDATE backfill_locks SET pid = ?, token = ? WHERE host = ? AND pid = ? AND token = ?", [state.pid, state.token, host, holder.pid, holder.token]);
             if (!replaced)

package/dist/importer/backfill-model.d.ts

@@ -1,5 +1,5 @@
 export type BackfillHost = "pi" | "opencode";
-export type BackfillModel = "inherit" | {
+export type BackfillModel = "inherit" | "external" | {
     provider: string;
     model: string;
 };

package/dist/importer/backfill-model.js

@@ -3,6 +3,8 @@ export function parseBackfillModel(config, host) {
     const value = host === "pi" ? config.piBackfillModel : config.opencodeBackfillModel;
     if (value === undefined || value === "inherit")
         return "inherit";
+    if (value === "external")
+        return "external";
     if (typeof value !== "string")
         throw new Error(`Invalid ${host}BackfillModel config`);
     const slash = value.indexOf("/");

package/dist/importer/external-api-test.d.ts

@@ -0,0 +1,18 @@
+import { CONFIG } from "../config.js";
+export type ExternalApiTestResult = {
+    ok: true;
+    model: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * One small call to the saved external API from this process, with a small
+ * output limit. The error never contains the key.
+ */
+export declare function testExternalApi(config?: typeof CONFIG, createProvider?: (provider: string, providerConfig: Record<string, unknown>) => {
+    executeToolCall: (...args: any[]) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}): Promise<ExternalApiTestResult>;

package/dist/importer/external-api-test.js

@@ -0,0 +1,50 @@
+import { randomUUID } from "node:crypto";
+import { CONFIG } from "../config.js";
+import { safeHealthError } from "../services/safe-health-error.js";
+const OUTPUT_LIMIT = 64;
+const TIMEOUT_MS = 20_000;
+/** Provider-specific output caps; Anthropic-style providers read `maxTokens`. */
+function outputLimitParams(provider) {
+    if (provider === "openai-chat" || provider === "orcarouter")
+        return { max_tokens: OUTPUT_LIMIT };
+    if (provider === "openai-responses")
+        return { max_output_tokens: OUTPUT_LIMIT };
+    return {};
+}
+/**
+ * One small call to the saved external API from this process, with a small
+ * output limit. The error never contains the key.
+ */
+export async function testExternalApi(config = CONFIG, createProvider) {
+    const secrets = [config.memoryApiKey];
+    try {
+        const { buildMemoryProviderConfig } = await import("../services/ai/provider-config.js");
+        const base = buildMemoryProviderConfig(config, {
+            maxIterations: 1,
+            iterationTimeout: TIMEOUT_MS,
+        });
+        const providerConfig = {
+            ...base,
+            maxTokens: OUTPUT_LIMIT,
+            extraParams: { ...base.extraParams, ...outputLimitParams(config.memoryProvider) },
+        };
+        const create = createProvider ??
+            (await import("../services/ai/ai-provider-factory.js")).AIProviderFactory.createProvider;
+        const provider = create(config.memoryProvider, providerConfig);
+        const tool = {
+            type: "function",
+            function: {
+                name: "acknowledge",
+                description: "Confirm the connection works",
+                parameters: { type: "object", properties: { ok: { type: "boolean" } }, required: ["ok"] },
+            },
+        };
+        const result = await provider.executeToolCall("You are testing a connection. Call the acknowledge tool with ok set to true.", "Acknowledge.", tool, `external-api-test-${randomUUID()}`);
+        if (!result.success)
+            throw new Error(result.error ?? "The external API call failed");
+        return { ok: true, model: `${config.memoryProvider}/${config.memoryModel ?? "default"}` };
+    }
+    catch (error) {
+        return { ok: false, error: safeHealthError(error, secrets).slice(0, 500) };
+    }
+}

package/dist/importer/external-backfill-models.d.ts

@@ -0,0 +1,15 @@
+import type { BackfillHost } from "./backfill-model.js";
+import type { SelectedImportModel } from "./model-selection.js";
+import type { HistoryImportModels } from "./run-import.js";
+interface ExternalConfig {
+    memoryProvider?: string;
+    memoryModel?: string;
+    memoryApiUrl?: string;
+    memoryApiKey?: string;
+}
+/** A backfill set to `external`: the external API, or an error naming the missing settings. */
+export declare function resolveExternalBackfillModels(host: BackfillHost, config: ExternalConfig, externalModels?: (flags: Record<string, never>) => SelectedImportModel): Promise<{
+    model: string;
+    models: HistoryImportModels;
+}>;
+export {};

package/dist/importer/external-backfill-models.js

@@ -0,0 +1,14 @@
+import { externalModelIssues } from "../services/ai/live-model-choice.js";
+/** A backfill set to `external`: the external API, or an error naming the missing settings. */
+export async function resolveExternalBackfillModels(host, config, externalModels) {
+    const issues = externalModelIssues(config);
+    const label = host === "pi" ? "Pi" : "OpenCode";
+    if (issues.length > 0)
+        throw new Error(`${label} backfill: ${issues.join("; ")}`);
+    const select = externalModels ?? (await import("./model-selection.js")).selectImportModel;
+    const external = select({});
+    return {
+        model: `${external.provider}/${external.modelId}`,
+        models: { capture: external.capture, profile: external.profile },
+    };
+}

package/dist/importer/import-path-maps.d.ts

@@ -0,0 +1,14 @@
+import type { ImportPathMap } from "./importer.js";
+/**
+ * Validate and normalise `importPathMaps` from the global config. Each entry
+ * needs absolute `from` and `to` directories after `~` expansion. Throws on
+ * the first invalid entry, like the rest of config validation.
+ */
+export declare function parseImportPathMaps(value: unknown): ImportPathMap[];
+/** Saved maps with the run's own maps on top; a run map wins for the same `from`. */
+export declare function mergeImportPathMaps(saved: readonly ImportPathMap[], run: readonly ImportPathMap[]): ImportPathMap[];
+/**
+ * The maps one import run uses: the saved `importPathMaps` with the run's
+ * maps on top, run targets resolved against `cwd`.
+ */
+export declare function runPathMaps(runMaps: readonly ImportPathMap[], cwd: string, saved?: readonly ImportPathMap[]): Promise<ImportPathMap[]>;

package/dist/importer/import-path-maps.js

@@ -0,0 +1,49 @@
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+function expandHome(path) {
+    if (path === "~")
+        return homedir();
+    if (path.startsWith("~/") || path.startsWith("~\\"))
+        return join(homedir(), path.slice(2));
+    return path;
+}
+/**
+ * Validate and normalise `importPathMaps` from the global config. Each entry
+ * needs absolute `from` and `to` directories after `~` expansion. Throws on
+ * the first invalid entry, like the rest of config validation.
+ */
+export function parseImportPathMaps(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("Invalid importPathMaps config: must be a list");
+    return value.map((entry, index) => {
+        const from = entry?.from;
+        const to = entry?.to;
+        if (typeof from !== "string" || typeof to !== "string" || !from.trim() || !to.trim()) {
+            throw new Error(`Invalid importPathMaps config: entry ${index} needs "from" and "to"`);
+        }
+        const expanded = { from: expandHome(from.trim()), to: expandHome(to.trim()) };
+        if (!isAbsolute(expanded.from) || !isAbsolute(expanded.to)) {
+            throw new Error(`Invalid importPathMaps config: entry ${index} needs absolute paths`);
+        }
+        return { from: resolve(expanded.from), to: resolve(expanded.to) };
+    });
+}
+/** Saved maps with the run's own maps on top; a run map wins for the same `from`. */
+export function mergeImportPathMaps(saved, run) {
+    const byFrom = new Map();
+    for (const map of saved)
+        byFrom.set(map.from, map);
+    for (const map of run)
+        byFrom.set(map.from, map);
+    return [...byFrom.values()];
+}
+/**
+ * The maps one import run uses: the saved `importPathMaps` with the run's
+ * maps on top, run targets resolved against `cwd`.
+ */
+export async function runPathMaps(runMaps, cwd, saved) {
+    const savedMaps = saved ?? (await import("../config.js")).CONFIG.importPathMaps ?? [];
+    return mergeImportPathMaps(savedMaps, runMaps.map((map) => ({ from: map.from, to: resolve(cwd, map.to) })));
+}

package/dist/importer/import-progress.d.ts

@@ -0,0 +1,27 @@
+/** One `(time, done)` reading of a running import. */
+export interface ProgressSample {
+    at: number;
+    done: number;
+}
+export declare const MAX_PROGRESS_SAMPLES = 20;
+/** Keep the most recent samples; a sample with no new units only moves the clock. */
+export declare function addProgressSample(samples: readonly ProgressSample[], sample: ProgressSample): ProgressSample[];
+export interface ProgressEstimate {
+    percent: number;
+    /** Null until the recent window has 5 samples spanning a minute and a non-zero rate. */
+    minutesLeft: number | null;
+    /** Units a minute over the recent window, or null while unknown. */
+    ratePerMinute: number | null;
+}
+/** Percentage done and minutes left from the recent sample window, not the whole run. */
+export declare function estimateProgress(total: number, done: number, samples: readonly ProgressSample[]): ProgressEstimate;
+/**
+ * Turn the importer's progress callback into finished work units. The
+ * importer reports a unit as it starts, and `alreadyHandled` (units found in
+ * the ledger, which need no model call) does not yet include that unit, so
+ * finished work is `processed - 1 - alreadyHandled`.
+ */
+export declare function workProgress(processed: number, total: number, alreadyHandled?: number, expectedTotal?: number): {
+    done: number;
+    total: number;
+};

package/dist/importer/import-progress.js

@@ -0,0 +1,38 @@
+export const MAX_PROGRESS_SAMPLES = 20;
+const MIN_SAMPLES = 5;
+const MIN_WINDOW_MS = 60_000;
+/** Keep the most recent samples; a sample with no new units only moves the clock. */
+export function addProgressSample(samples, sample) {
+    return [...samples, sample].slice(-MAX_PROGRESS_SAMPLES);
+}
+/** Percentage done and minutes left from the recent sample window, not the whole run. */
+export function estimateProgress(total, done, samples) {
+    const percent = total > 0 ? Math.min(100, Math.floor((done / total) * 100)) : 0;
+    if (samples.length < MIN_SAMPLES)
+        return { percent, minutesLeft: null, ratePerMinute: null };
+    const first = samples[0];
+    const last = samples[samples.length - 1];
+    const span = last.at - first.at;
+    if (span < MIN_WINDOW_MS || last.done <= first.done) {
+        return { percent, minutesLeft: null, ratePerMinute: null };
+    }
+    const ratePerMinute = (last.done - first.done) / (span / 60_000);
+    return {
+        percent,
+        minutesLeft: Math.max(0, Math.round((total - done) / ratePerMinute)),
+        ratePerMinute,
+    };
+}
+/**
+ * Turn the importer's progress callback into finished work units. The
+ * importer reports a unit as it starts, and `alreadyHandled` (units found in
+ * the ledger, which need no model call) does not yet include that unit, so
+ * finished work is `processed - 1 - alreadyHandled`.
+ */
+export function workProgress(processed, total, alreadyHandled = 0, expectedTotal) {
+    const workTotal = Math.max(0, expectedTotal ?? total - alreadyHandled);
+    return {
+        done: Math.min(workTotal, Math.max(0, processed - 1 - alreadyHandled)),
+        total: workTotal,
+    };
+}

package/dist/importer/import-runs.d.ts

@@ -0,0 +1,43 @@
+import type { BackfillHost } from "./backfill-model.js";
+import { type ProgressEstimate } from "./import-progress.js";
+export type ImportSurface = "auto" | "web" | "cli" | "slash";
+export type ImportRunState = "running" | "paused" | "stopped" | "done" | "failed";
+export interface ImportRunCounts {
+    total: number;
+    done: number;
+    imported: number;
+    skipped: number;
+    failed: number;
+}
+export interface ImportRun extends ImportRunCounts, ProgressEstimate {
+    host: BackfillHost;
+    surface: ImportSurface | null;
+    state: ImportRunState | null;
+    pid: number | null;
+    startedAt: number | null;
+    updatedAt: number | null;
+    error: string | null;
+    /** The user paused this host's backfill; automatic runs wait for Resume. */
+    paused: boolean;
+}
+/** Read a host's run without creating the store; a running row whose process is gone reads as stopped. */
+export declare function readImportRun(host: BackfillHost): Promise<ImportRun | null>;
+export declare function isBackfillPaused(host: BackfillHost): Promise<boolean>;
+export declare function setBackfillPaused(host: BackfillHost, paused: boolean): Promise<void>;
+export interface ImportRunRecorder {
+    /** Feed from `onProgress`; writes at most once per interval and checks the paused flag. */
+    progress(done: number, total: number): void;
+    /** True after a progress write saw the paused flag. */
+    readonly pauseRequested: boolean;
+    finish(state: Exclude<ImportRunState, "running">, counts: Partial<ImportRunCounts>, error?: unknown): Promise<void>;
+}
+/**
+ * Start a host's run record. Only numbers, the surface, and the PID are
+ * stored; `promptPreview` and all other conversation content never are.
+ */
+export declare function startImportRun(host: BackfillHost, surface: ImportSurface, options?: {
+    now?: () => number;
+    intervalMs?: number;
+    sampleIntervalMs?: number;
+    onPause?: () => void;
+}): Promise<ImportRunRecorder>;