om-memory-system 3.2.0-next.9 → 3.3.0-next.18

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

@@ -0,0 +1,20 @@
+import type { BackfillHost } from "./backfill-model.js";
+import { runHistoryImport, type HistoryImportModels } from "./run-import.js";
+type Run = typeof runHistoryImport;
+export interface AutoBackfillOptions {
+    host: BackfillHost;
+    cwd: string;
+    resolveModels: () => Promise<{
+        model: string;
+        models: HistoryImportModels;
+    }>;
+    notify: (message: string) => void;
+    run?: Run;
+    wait?: () => Promise<void>;
+    now?: () => number;
+    enabled?: () => boolean;
+    signal?: AbortSignal;
+}
+/** Schedule one host's history import after startup; callers do not await it. */
+export declare function scheduleAutoBackfill(options: AutoBackfillOptions): Promise<void>;
+export {};

package/dist/importer/auto-backfill.js

@@ -0,0 +1,165 @@
+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 { runHistoryImport, } from "./run-import.js";
+import { isManualImportRunning } from "./manual-import-guard.js";
+const zero = () => ({ imported: 0, skipped: 0, failed: 0, pending: 0, unresolved: 0 });
+function counts(report) {
+    return {
+        imported: report.unitsImported,
+        skipped: report.unitsSkipped,
+        failed: report.unitsFailed,
+        pending: report.unitsWouldImport,
+        unresolved: (report.unresolvedProjects?.length ?? 0) + report.unresolvableSessions.length,
+    };
+}
+const delay = (signal) => new Promise((resolve) => {
+    if (signal?.aborted)
+        return resolve();
+    const done = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", done);
+        resolve();
+    };
+    const timer = setTimeout(done, 30_000);
+    signal?.addEventListener("abort", done, { once: true });
+});
+/** 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.signal?.aborted)
+        return;
+    if (!(options.enabled ??
+        (() => CONFIG.autoBackfill && process.env.OMMS_DISABLE_AUTO_BACKFILL !== "1"))())
+        return;
+    if (isManualImportRunning(options.host))
+        return;
+    const release = await tryAcquireBackfillLock(options.host);
+    if (!release)
+        return;
+    const clock = options.now ?? Date.now;
+    const run = options.run ?? runHistoryImport;
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    if (options.signal?.aborted)
+        controller.abort();
+    let state = "failed";
+    let model = null;
+    let current = zero();
+    let lastError;
+    try {
+        if (controller.signal.aborted) {
+            state = "stopped";
+            return;
+        }
+        const cutoff = await getBackfillCutoff(options.host, clock());
+        const args = {
+            help: false,
+            dryRun: true,
+            force: false,
+            skipMemories: false,
+            skipProfile: false,
+            scope: "all-projects",
+            pathMaps: [],
+            until: cutoff,
+            errors: [],
+        };
+        const dry = await run(options.host, args, {
+            cwd: options.cwd,
+            models: {},
+            signal: controller.signal,
+        });
+        current = counts(dry);
+        if (controller.signal.aborted) {
+            state = "stopped";
+            return;
+        }
+        if (!current.pending) {
+            state = "done";
+            return;
+        }
+        const resolved = await options.resolveModels();
+        if (controller.signal.aborted) {
+            state = "stopped";
+            return;
+        }
+        model = resolved.model;
+        options.notify(`${options.host} automatic import: ${current.pending} exchanges with ${model}. Set autoBackfill to false to stop it.`);
+        state = "running";
+        await updateBackfillStatus(options.host, { state, model, counts: current });
+        if (controller.signal.aborted) {
+            state = "stopped";
+            return;
+        }
+        let failures = 0;
+        const capture = resolved.models.capture;
+        const models = capture
+            ? {
+                ...resolved.models,
+                capture: {
+                    summarize: async (request) => {
+                        try {
+                            const result = await capture.summarize(request);
+                            failures = 0;
+                            return result;
+                        }
+                        catch (error) {
+                            lastError = error;
+                            if (++failures >= 5)
+                                controller.abort();
+                            throw error;
+                        }
+                    },
+                },
+            }
+            : resolved.models;
+        let checkedAt = clock();
+        let processed = 0;
+        let pendingWrite = Promise.resolve();
+        const real = await run(options.host, { ...args, dryRun: false }, {
+            cwd: options.cwd,
+            models,
+            signal: controller.signal,
+            onProgress: (done, total) => {
+                processed = done;
+                const now = clock();
+                if (now - checkedAt < 5_000)
+                    return;
+                checkedAt = now;
+                refreshConfigIfChanged(options.cwd);
+                if (!CONFIG.autoBackfill)
+                    controller.abort();
+                current = { ...current, pending: Math.max(0, total - done) };
+                pendingWrite = pendingWrite
+                    .then(() => updateBackfillStatus(options.host, { state: "running", model, counts: current }))
+                    .catch((error) => {
+                    log("Backfill status write failed", {
+                        host: options.host,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                });
+            },
+        });
+        await pendingWrite;
+        current = { ...counts(real), pending: Math.max(0, dry.unitsWouldImport - processed) };
+        state = controller.signal.aborted ? "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.`);
+        }
+    }
+    catch (error) {
+        lastError = error;
+        state = controller.signal.aborted ? "stopped" : "failed";
+    }
+    finally {
+        try {
+            await updateBackfillStatus(options.host, { state, model, counts: current, error: lastError });
+        }
+        finally {
+            options.signal?.removeEventListener("abort", onAbort);
+            await release();
+        }
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { BackfillHost } from "./backfill-model.js";
+/** 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

@@ -0,0 +1,44 @@
+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) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** Claim one host's import without holding a database transaction during the run. */
+export async function tryAcquireBackfillLock(host, storagePath = CONFIG.storagePath) {
+    const db = await tursoConnectionManager.getConnection(join(storagePath, "import-ledger.db"));
+    await db.run(`CREATE TABLE IF NOT EXISTS backfill_locks (
+    host TEXT PRIMARY KEY, pid INTEGER NOT NULL, token TEXT NOT NULL
+  )`);
+    const state = { pid: process.pid, token: randomUUID() };
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const inserted = await db.run("INSERT OR IGNORE INTO backfill_locks (host, pid, token) VALUES (?, ?, ?)", [host, state.pid, state.token]);
+        if (!inserted) {
+            const holder = await db.get("SELECT pid, token FROM backfill_locks WHERE host = ?", [host]);
+            if (!holder)
+                continue;
+            if (live(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)
+                continue;
+        }
+        let released = false;
+        return async () => {
+            if (released)
+                return;
+            released = true;
+            await db.run("DELETE FROM backfill_locks WHERE host = ? AND token = ?", [host, state.token]);
+        };
+    }
+    return null;
+}

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

@@ -0,0 +1,10 @@
+export type BackfillHost = "pi" | "opencode";
+export type BackfillModel = "inherit" | {
+    provider: string;
+    model: string;
+};
+/** Parse the global backfill model without importing the runtime config. */
+export declare function parseBackfillModel(config: {
+    piBackfillModel?: unknown;
+    opencodeBackfillModel?: unknown;
+}, host: BackfillHost): BackfillModel;

package/dist/importer/backfill-model.js

@@ -0,0 +1,13 @@
+/** Parse the global backfill model without importing the runtime config. */
+export function parseBackfillModel(config, host) {
+    const value = host === "pi" ? config.piBackfillModel : config.opencodeBackfillModel;
+    if (value === undefined || value === "inherit")
+        return "inherit";
+    if (typeof value !== "string")
+        throw new Error(`Invalid ${host}BackfillModel config`);
+    const slash = value.indexOf("/");
+    if (slash <= 0 || slash === value.length - 1) {
+        throw new Error(`Invalid ${host}BackfillModel config`);
+    }
+    return { provider: value.slice(0, slash), model: value.slice(slash + 1) };
+}

package/dist/importer/discovery.d.ts

@@ -1,15 +1,21 @@
 /**
  * Discovery of Pi session files for the historical importer. Read-only: only
- * the first line (the session header) is parsed here, so discovery stays cheap
- * and full parsing happens later per candidate session.
+ * the first line (the session header) is parsed here, from at most the first
+ * 64 KB of each file, so discovery stays cheap on large histories and full
+ * parsing happens later per candidate session.
  *
- * Files that are not Pi session format (for example subagent artifacts, which
- * use a different record format without a `type: "session"` header) are
- * reported as unrecognized and skipped rather than treated as errors.
+ * The root may be a sessions folder or one `.jsonl` session file. Files that
+ * are not Pi session format (for example subagent artifacts, which use a
+ * different record format without a `type: "session"` header) are reported
+ * as unrecognized and skipped rather than treated as errors. Symlinked entries
+ * inside a folder are never followed.
  */
 export declare const DEFAULT_PI_SESSION_ROOT: string;
+export declare const PI_HEADER_READ_LIMIT: number;
 export interface DiscoveredPiSession {
     file: string;
+    /** Path relative to the root, with `/` separators; the file name for a file root. */
+    key: string;
     sessionId: string | null;
     cwd: string | null;
     version: number | null;
@@ -24,8 +30,29 @@ export interface DiscoveryResult {
     sessions: DiscoveredPiSession[];
     unrecognized: UnrecognizedFile[];
 }
+/**
+ * Bounds on a folder walk. A Pi sessions folder holds a few hundred folders,
+ * so a walk past the folder or file limit is almost certainly a home folder,
+ * `/`, or a whole backup volume, and would block the process for minutes.
+ * Depth is only a backstop: subagent runs nest session folders seven or more
+ * levels deep (`<project>/<run>/<id>/run-0/session/<id>/run-0`).
+ */
+export interface DiscoveryLimits {
+    maxDepth: number;
+    maxFolders: number;
+    maxFiles: number;
+}
+export declare const DEFAULT_DISCOVERY_LIMITS: DiscoveryLimits;
+export declare class DiscoveryLimitError extends Error {
+    constructor();
+}
 export interface DiscoveryOptions {
     root?: string;
     maxSessions?: number;
+    limits?: DiscoveryLimits;
 }
+/** Read the first line of a file without reading past `PI_HEADER_READ_LIMIT` bytes. */
+export declare function readFirstLine(file: string, limit?: number): string;
+/** Parse one file's header, or say why the file is not a Pi session. */
+export declare function readPiSessionHeader(file: string, key: string): DiscoveredPiSession | UnrecognizedFile;
 export declare function discoverPiSessions(options?: DiscoveryOptions): DiscoveryResult;

package/dist/importer/discovery.js

@@ -1,22 +1,39 @@
-import { readdirSync, readFileSync } from "node:fs";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { closeSync, existsSync, openSync, readSync, readdirSync, statSync } from "node:fs";
+import { basename, join, relative, sep } from "node:path";
 import { homedir } from "node:os";
 /**
  * Discovery of Pi session files for the historical importer. Read-only: only
- * the first line (the session header) is parsed here, so discovery stays cheap
- * and full parsing happens later per candidate session.
+ * the first line (the session header) is parsed here, from at most the first
+ * 64 KB of each file, so discovery stays cheap on large histories and full
+ * parsing happens later per candidate session.
  *
- * Files that are not Pi session format (for example subagent artifacts, which
- * use a different record format without a `type: "session"` header) are
- * reported as unrecognized and skipped rather than treated as errors.
+ * The root may be a sessions folder or one `.jsonl` session file. Files that
+ * are not Pi session format (for example subagent artifacts, which use a
+ * different record format without a `type: "session"` header) are reported
+ * as unrecognized and skipped rather than treated as errors. Symlinked entries
+ * inside a folder are never followed.
  */
 export const DEFAULT_PI_SESSION_ROOT = join(homedir(), ".pi", "agent", "sessions");
-function listJsonlFiles(root) {
+export const PI_HEADER_READ_LIMIT = 64 * 1024;
+export const DEFAULT_DISCOVERY_LIMITS = {
+    maxDepth: 32,
+    maxFolders: 5_000,
+    maxFiles: 20_000,
+};
+export class DiscoveryLimitError extends Error {
+    constructor() {
+        super("This folder is too large to scan for Pi sessions. Choose the Pi sessions folder itself, or one .jsonl file.");
+        this.name = "DiscoveryLimitError";
+    }
+}
+function listJsonlFiles(root, limits) {
     const files = [];
-    const stack = [root];
+    const stack = [{ dir: root, depth: 0 }];
+    let folders = 0;
     while (stack.length > 0) {
-        const dir = stack.pop();
+        const { dir, depth } = stack.pop();
+        if (++folders > limits.maxFolders)
+            throw new DiscoveryLimitError();
         let entries;
         try {
             entries = readdirSync(dir, { withFileTypes: true });
@@ -27,29 +44,71 @@ function listJsonlFiles(root) {
         for (const entry of entries) {
             const full = join(dir, entry.name);
             if (entry.isDirectory()) {
-                stack.push(full);
+                if (depth + 1 > limits.maxDepth)
+                    throw new DiscoveryLimitError();
+                stack.push({ dir: full, depth: depth + 1 });
             }
             else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+                if (files.length >= limits.maxFiles)
+                    throw new DiscoveryLimitError();
                 files.push(full);
             }
         }
     }
     return files.sort();
 }
+/** Read the first line of a file without reading past `PI_HEADER_READ_LIMIT` bytes. */
+export function readFirstLine(file, limit = PI_HEADER_READ_LIMIT) {
+    const fd = openSync(file, "r");
+    try {
+        const buffer = Buffer.alloc(limit);
+        const read = readSync(fd, buffer, 0, limit, 0);
+        const text = buffer.subarray(0, read).toString("utf8");
+        const newline = text.indexOf("\n");
+        return newline === -1 ? text : text.slice(0, newline);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 function readHeaderLine(file) {
-    let firstLine;
     try {
-        const stream = readFileSync(file, "utf8");
-        const newline = stream.indexOf("\n");
-        firstLine = (newline === -1 ? stream : stream.slice(0, newline)).trim();
+        const firstLine = readFirstLine(file).trim();
         if (!firstLine)
             return { error: "empty file" };
         return { header: JSON.parse(firstLine) };
     }
     catch (error) {
         if (error instanceof SyntaxError)
-            return { error: `malformed header: ${String(error)}` };
-        return { error: `unreadable: ${String(error)}` };
+            return { error: "malformed header" };
+        return { error: `unreadable: ${error.code ?? "error"}` };
+    }
+}
+/** Parse one file's header, or say why the file is not a Pi session. */
+export function readPiSessionHeader(file, key) {
+    const parsed = readHeaderLine(file);
+    if ("error" in parsed)
+        return { file, reason: parsed.error };
+    const header = parsed.header;
+    if (header?.type !== "session") {
+        return { file, reason: "not a Pi session file (no session header)" };
+    }
+    const timestamp = typeof header.timestamp === "string" ? Date.parse(header.timestamp) : NaN;
+    return {
+        file,
+        key,
+        sessionId: typeof header.id === "string" ? header.id : null,
+        cwd: typeof header.cwd === "string" ? header.cwd : null,
+        version: typeof header.version === "number" ? header.version : null,
+        timestamp: Number.isNaN(timestamp) ? null : timestamp,
+    };
+}
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
     }
 }
 export function discoverPiSessions(options = {}) {
@@ -59,25 +118,18 @@ export function discoverPiSessions(options = {}) {
     if (!existsSync(root)) {
         return { sessions, unrecognized };
     }
-    for (const file of listJsonlFiles(root)) {
-        const parsed = readHeaderLine(file);
-        if ("error" in parsed) {
-            unrecognized.push({ file, reason: parsed.error });
-            continue;
-        }
-        const header = parsed.header;
-        if (header?.type !== "session") {
-            unrecognized.push({ file, reason: "not a Pi session file (no session header)" });
-            continue;
-        }
-        const timestamp = typeof header.timestamp === "string" ? Date.parse(header.timestamp) : NaN;
-        sessions.push({
+    const files = isFile(root)
+        ? [{ file: root, key: basename(root) }]
+        : listJsonlFiles(root, options.limits ?? DEFAULT_DISCOVERY_LIMITS).map((file) => ({
             file,
-            sessionId: typeof header.id === "string" ? header.id : null,
-            cwd: typeof header.cwd === "string" ? header.cwd : null,
-            version: typeof header.version === "number" ? header.version : null,
-            timestamp: Number.isNaN(timestamp) ? null : timestamp,
-        });
+            key: relative(root, file).split(sep).join("/"),
+        }));
+    for (const { file, key } of files) {
+        const result = readPiSessionHeader(file, key);
+        if ("reason" in result)
+            unrecognized.push(result);
+        else
+            sessions.push(result);
     }
     // Chronological order, oldest first; files without a timestamp sort last.
     sessions.sort((a, b) => (a.timestamp ?? Infinity) - (b.timestamp ?? Infinity));

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

@@ -7,7 +7,7 @@ import type { ImportPathMap } from "./importer.js";
  * external API and key).
  */
 export type ImportHost = "pi" | "opencode";
-export type ImportSurface = "session" | "cli";
+export type ImportSurface = "session" | "cli" | "web";
 export interface HistoryImportArgs {
     help: boolean;
     dryRun: boolean;
@@ -39,6 +39,28 @@ export declare function parseHistoryImportArgs(tokens: string[], options: {
     host: ImportHost;
     surface: ImportSurface;
 }): HistoryImportArgs;
+/**
+ * Options the Settings page sends. Sessions come from the page's selection
+ * and the source from a signed token, so there is no `session`,
+ * `maxSessions`, or `source` here.
+ */
+export interface WebImportOptions {
+    dryRun?: boolean;
+    force?: boolean;
+    skipMemories?: boolean;
+    skipProfile?: boolean;
+    model?: string;
+    scope?: HistoryImportArgs["scope"];
+    project?: string;
+    /** Epoch ms from the browser's local day start, or an ISO date. */
+    since?: string | number;
+    /** Epoch ms from the browser's local day end, or an ISO date. */
+    until?: string | number;
+    profileBatch?: number;
+    pathMaps?: ImportPathMap[];
+}
+/** Convert page fields to the shared CLI grammar, which performs validation. */
+export declare function webImportTokens(options: WebImportOptions, _host: ImportHost): string[];
 /** True when the run calls a model: a real import of memories or the profile. */
 export declare function importNeedsModel(args: HistoryImportArgs): boolean;
 export declare function historyImportUsage(host: ImportHost, surface: ImportSurface): string;

package/dist/importer/import-args.js

@@ -168,7 +168,7 @@ export function parseHistoryImportArgs(tokens, options) {
     if (result.project !== undefined && result.scope === "all-projects") {
         result.errors.push("--project cannot be combined with --scope=all-projects");
     }
-    if (options.surface === "session" && result.model !== undefined) {
+    if (options.surface !== "cli" && result.model !== undefined) {
         const separator = result.model.indexOf("/");
         if (separator < 1 || separator === result.model.length - 1) {
             result.errors.push(`--model must be provider/id, got "${result.model}"`);
@@ -176,6 +176,34 @@ export function parseHistoryImportArgs(tokens, options) {
     }
     return result;
 }
+/** Convert page fields to the shared CLI grammar, which performs validation. */
+export function webImportTokens(options, _host) {
+    const tokens = [];
+    for (const [field, flag] of [
+        ["dryRun", "--dry-run"],
+        ["force", "--force"],
+        ["skipMemories", "--skip-memories"],
+        ["skipProfile", "--skip-profile"],
+    ]) {
+        if (options[field])
+            tokens.push(flag);
+    }
+    for (const [field, flag] of [
+        ["model", "--model"],
+        ["scope", "--scope"],
+        ["project", "--project"],
+        ["since", "--since"],
+        ["until", "--until"],
+        ["profileBatch", "--profile-batch"],
+    ]) {
+        const value = options[field];
+        if (value !== undefined)
+            tokens.push(flag, String(value));
+    }
+    for (const map of options.pathMaps ?? [])
+        tokens.push("--map", `${map.from}=${map.to}`);
+    return tokens;
+}
 /** True when the run calls a model: a real import of memories or the profile. */
 export function importNeedsModel(args) {
     return !args.dryRun && (!args.skipMemories || !args.skipProfile);

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

@@ -0,0 +1,16 @@
+import type { ImportPathMap } from "./importer.js";
+/** How a recorded session directory was turned into a project directory. */
+export type ProjectResolution = "mapped" | "recorded" | "worktree" | "unresolved";
+export interface ResolvedImportProject {
+    directory: string | null;
+    via: ProjectResolution;
+}
+/**
+ * One rule for both hosts, shared by the web session list and the importers so
+ * the listed set and the imported set always agree. An exact directory map
+ * wins, because it is an explicit user choice; a map whose target is missing
+ * leaves the session unresolved rather than silently falling back. OpenCode
+ * alone passes a project worktree, which stands in for a deleted sub-directory
+ * of the same project.
+ */
+export declare function resolveImportProject(recordedDirectory: string | null, maps?: ImportPathMap[], projectWorktree?: string | null): ResolvedImportProject;

package/dist/importer/import-project.js

@@ -0,0 +1,35 @@
+import { statSync } from "node:fs";
+function isDirectory(path) {
+    if (!path)
+        return false;
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * One rule for both hosts, shared by the web session list and the importers so
+ * the listed set and the imported set always agree. An exact directory map
+ * wins, because it is an explicit user choice; a map whose target is missing
+ * leaves the session unresolved rather than silently falling back. OpenCode
+ * alone passes a project worktree, which stands in for a deleted sub-directory
+ * of the same project.
+ */
+export function resolveImportProject(recordedDirectory, maps = [], projectWorktree = null) {
+    if (!recordedDirectory)
+        return { directory: null, via: "unresolved" };
+    const map = maps.find((item) => item.from === recordedDirectory);
+    if (map) {
+        return isDirectory(map.to)
+            ? { directory: map.to, via: "mapped" }
+            : { directory: null, via: "unresolved" };
+    }
+    if (isDirectory(recordedDirectory))
+        return { directory: recordedDirectory, via: "recorded" };
+    if (projectWorktree && projectWorktree !== "/" && isDirectory(projectWorktree)) {
+        return { directory: projectWorktree, via: "worktree" };
+    }
+    return { directory: null, via: "unresolved" };
+}

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

@@ -0,0 +1,47 @@
+/**
+ * What a real web import could use right now, checked inside the OpenCode
+ * process that runs it. `env://` and `file://` keys were resolved when the
+ * config loaded, so a variable set only in the user's shell shows as missing.
+ * "Ready" means configured, not tested: the Health section runs test calls.
+ */
+export type ExternalApiState = "ready" | "missing-model" | "missing-url" | "missing-key" | "unsupported-provider";
+export interface ImportReadiness {
+    external: {
+        state: ExternalApiState;
+        provider: string;
+        model: string | null;
+    };
+    opencode: {
+        available: boolean;
+        models: Array<{
+            provider: string;
+            model: string;
+            name: string;
+        }>;
+    };
+    piReader: {
+        available: boolean;
+        reason?: string;
+    };
+}
+export interface ReadinessDeps {
+    supportedProviders?: () => Promise<string[]>;
+    listOpencodeModels?: () => Promise<{
+        available: boolean;
+        models?: Array<{
+            provider: string;
+            model: string;
+            name: string;
+        }>;
+    }>;
+    loadPiSdk?: () => Promise<unknown>;
+}
+/** Mirrors the checks in `selectImportModel`, without building a provider. */
+export declare function externalApiState(supportedProviders?: () => Promise<string[]>): Promise<ExternalApiState>;
+export declare function importReadiness(deps?: ReadinessDeps): Promise<ImportReadiness>;
+/** Why a job cannot start, or `null` when it can. */
+export declare function importBlockedReason(readiness: ImportReadiness, request: {
+    host: "pi" | "opencode";
+    needsModel: boolean;
+    modelChoice?: string;
+}): string | null;