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

package/dist/importer/import-readiness.js

@@ -0,0 +1,54 @@
+import { CONFIG } from "../config.js";
+const EXTERNAL_REASONS = {
+    "missing-model": "The external API has no memoryModel in the global config",
+    "missing-url": "The external API has no memoryApiUrl in the global config",
+    "missing-key": "The external API key is missing in the OpenCode process; check memoryApiKey and its env:// or file:// source",
+    "unsupported-provider": "The memoryProvider in the global config is not supported for imports",
+};
+/** Mirrors the checks in `selectImportModel`, without building a provider. */
+export async function externalApiState(supportedProviders = async () => (await import("../services/ai/ai-provider-factory.js")).AIProviderFactory.getSupportedProviders()) {
+    const provider = CONFIG.memoryProvider;
+    if (!(await supportedProviders()).includes(provider))
+        return "unsupported-provider";
+    if (provider !== "orcarouter") {
+        if (!CONFIG.memoryModel)
+            return "missing-model";
+        if (!CONFIG.memoryApiUrl)
+            return "missing-url";
+    }
+    if (!CONFIG.memoryApiKey)
+        return "missing-key";
+    return "ready";
+}
+export async function importReadiness(deps = {}) {
+    const [state, opencode, piReader] = await Promise.all([
+        externalApiState(deps.supportedProviders),
+        (deps.listOpencodeModels ??
+            (async () => (await import("../services/settings-models.js")).listOpencodeSettingsModels()))(),
+        (deps.loadPiSdk ?? (() => import("@earendil-works/pi-coding-agent")))().then(() => ({ available: true }), () => ({
+            available: false,
+            reason: "The Pi SDK (@earendil-works/pi-coding-agent) is not installed for OpenCode",
+        })),
+    ]);
+    return {
+        external: { state, provider: CONFIG.memoryProvider, model: CONFIG.memoryModel ?? null },
+        opencode: { available: opencode.available, models: opencode.models ?? [] },
+        piReader,
+    };
+}
+/** Why a job cannot start, or `null` when it can. */
+export function importBlockedReason(readiness, request) {
+    if (request.host === "pi" && !readiness.piReader.available) {
+        return readiness.piReader.reason ?? "The Pi session reader is unavailable";
+    }
+    if (!request.needsModel)
+        return null;
+    if (!request.modelChoice)
+        return "Choose an import model";
+    if (request.modelChoice === "external") {
+        const state = readiness.external.state;
+        return state === "ready" ? null : EXTERNAL_REASONS[state];
+    }
+    const connected = readiness.opencode.models.some((model) => `${model.provider}/${model.model}` === request.modelChoice);
+    return connected ? null : "The chosen OpenCode model is not connected";
+}

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

@@ -0,0 +1,98 @@
+import type { HistoryImportArgs, ImportHost } from "./import-args.js";
+import { type ProjectResolution } from "./import-project.js";
+import { type ImportSourceIdentity } from "./import-sources.js";
+import type { ImportPathMap } from "./importer.js";
+/**
+ * Session metadata for the Settings page and the selection a job imports.
+ * Both come from `matchImportSessions`, so the list, its revision, and the
+ * imported set always use the same discovery and project rules.
+ */
+export declare const MAX_SELECTED_KEYS = 1000;
+export interface ImportSessionRow {
+    /** Selection key: the OpenCode session ID, or the Pi file path relative to the source. */
+    key: string;
+    sessionId: string | null;
+    createdAt: number | null;
+    recordedDirectory: string | null;
+    directory: string | null;
+    via: ProjectResolution;
+}
+export interface ImportMatchOptions {
+    host: ImportHost;
+    scope: HistoryImportArgs["scope"];
+    /** Absolute project directory; defaults to the server's working directory. */
+    project?: string;
+    pathMaps: ImportPathMap[];
+    cwd: string;
+}
+export declare class StaleSelectionError extends Error {
+    readonly status = 409;
+    constructor(message?: string);
+}
+interface Matched {
+    identity: ImportSourceIdentity;
+    /** Resolvable sessions in scope, newest first. */
+    matching: ImportSessionRow[];
+    /** Sessions whose directory cannot be resolved, in any scope. */
+    unresolved: ImportSessionRow[];
+    revision: string;
+}
+export declare function matchImportSessions(identity: ImportSourceIdentity, options: ImportMatchOptions, snapshotMode: "fresh" | "reuse" | "any"): Promise<Matched>;
+export interface ImportSessionPage {
+    source: {
+        kind: ImportSourceIdentity["kind"];
+        displayPath: string;
+        sourceToken: string;
+    };
+    total: number;
+    offset: number;
+    rows: Array<ImportSessionRow & {
+        selectable: boolean;
+    }>;
+    /** Sessions whose recorded directory no longer exists. */
+    unresolvedCount: number;
+    revision: string;
+    listedAt: number;
+}
+export interface SessionListRequest {
+    sourceToken?: unknown;
+    offset?: number;
+    limit?: number;
+    refresh?: boolean;
+    match: Omit<ImportMatchOptions, "cwd">;
+}
+/** Check a session-list request body from the page. */
+export declare function validateSessionListRequest(value: unknown): SessionListRequest;
+/** One page of session metadata; no prompts, replies, or tool data. */
+export declare function listImportSessions(request: {
+    sourceToken?: unknown;
+    offset?: number;
+    limit?: number;
+    refresh?: boolean;
+}, options: ImportMatchOptions): Promise<ImportSessionPage>;
+export type ImportSelection = {
+    mode: "ids";
+    sessions: Array<{
+        key: string;
+        directory: string;
+    }>;
+    listedAt: number;
+} | {
+    mode: "all";
+    excludedKeys: string[];
+    revision: string;
+    listedAt: number;
+};
+export declare function validateImportSelection(value: unknown): ImportSelection;
+export interface ResolvedImportSelection {
+    identity: ImportSourceIdentity;
+    keys: string[];
+    cutoff: number;
+}
+/**
+ * Re-resolve a selection against the source right before a job. New sessions
+ * make an "all" selection stale; a missing or re-projected session makes an
+ * "ids" selection stale. Neither ever imports a session the user did not see.
+ */
+export declare function resolveImportSelection(sourceToken: unknown, selection: ImportSelection, options: ImportMatchOptions): Promise<ResolvedImportSelection>;
+export {};

package/dist/importer/import-sessions.js

@@ -0,0 +1,222 @@
+import { createHash } from "node:crypto";
+import { isAbsolute, resolve } from "node:path";
+import { discoverPiSessions } from "./discovery.js";
+import { resolveImportProject } from "./import-project.js";
+import { assertImportSourceUnchanged, importSourceKey, readImportSourceToken, validateImportSource, defaultImportSourcePath, } from "./import-sources.js";
+/**
+ * Session metadata for the Settings page and the selection a job imports.
+ * Both come from `matchImportSessions`, so the list, its revision, and the
+ * imported set always use the same discovery and project rules.
+ */
+export const MAX_SELECTED_KEYS = 1000;
+const MAX_PAGE = 200;
+export class StaleSelectionError extends Error {
+    status = 409;
+    constructor(message = "The session list is out of date. Refresh the list and try again.") {
+        super(message);
+        this.name = "StaleSelectionError";
+    }
+}
+async function readRows(identity, options, snapshotMode) {
+    if (options.host === "pi") {
+        return discoverPiSessions({ root: identity.realPath }).sessions.map((session) => ({
+            key: session.key,
+            sessionId: session.sessionId,
+            createdAt: session.timestamp,
+            recordedDirectory: session.cwd,
+            ...resolveImportProject(session.cwd, options.pathMaps),
+        }));
+    }
+    const { openOpencodeHistory } = await import("./opencode-reader.js");
+    const history = await openOpencodeHistory(identity.realPath, {}, { shared: { key: importSourceKey(identity), mode: snapshotMode } });
+    try {
+        return history.sessions.map((session) => ({
+            key: session.sessionId,
+            sessionId: session.sessionId,
+            createdAt: session.timeCreated,
+            recordedDirectory: session.recordedDirectory,
+            ...resolveImportProject(session.recordedDirectory, options.pathMaps, session.projectWorktree),
+        }));
+    }
+    finally {
+        await history.close();
+    }
+}
+/**
+ * The revision covers the source, the options that decide membership, and the
+ * sorted keys. It never uses file sizes or times: a live database changes on
+ * every message, and new turns in a listed session do not change the set.
+ */
+function revisionOf(identity, options, projectTag, keys) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        host: options.host,
+        source: importSourceKey(identity),
+        scope: options.scope,
+        project: projectTag,
+        maps: options.pathMaps,
+        keys: [...keys].sort(),
+    }))
+        .digest("hex");
+}
+export async function matchImportSessions(identity, options, snapshotMode) {
+    assertImportSourceUnchanged(identity);
+    const { projectFilterTag } = await import("./importer.js");
+    const projectTag = options.scope === "current-project"
+        ? projectFilterTag(resolve(options.cwd, options.project ?? "."))
+        : null;
+    // Map targets resolve against the working directory, as `runHistoryImport` does.
+    const rows = await readRows(identity, {
+        ...options,
+        pathMaps: options.pathMaps.map((map) => ({
+            from: map.from,
+            to: resolve(options.cwd, map.to),
+        })),
+    }, snapshotMode);
+    const unresolved = rows.filter((row) => row.directory === null);
+    const matching = rows
+        .filter((row) => row.directory !== null)
+        .filter((row) => projectTag === null || projectFilterTag(row.directory) === projectTag)
+        .sort((a, b) => (b.createdAt ?? 0) - (a.createdAt ?? 0) || a.key.localeCompare(b.key));
+    return {
+        identity,
+        matching,
+        unresolved,
+        revision: revisionOf(identity, options, projectTag, matching.map((row) => row.key)),
+    };
+}
+/** Check a session-list request body from the page. */
+export function validateSessionListRequest(value) {
+    const input = value;
+    if (!input || typeof input !== "object")
+        throw new Error("Invalid session list request");
+    if (input.host !== "pi" && input.host !== "opencode")
+        throw new Error("Choose Pi or OpenCode");
+    const scope = input.scope ?? "current-project";
+    if (scope !== "current-project" && scope !== "all-projects")
+        throw new Error("Invalid scope");
+    const project = input.project;
+    if (project !== undefined && (typeof project !== "string" || !isAbsolute(project))) {
+        throw new Error("The project must be an absolute path");
+    }
+    const maps = input.pathMaps ?? [];
+    if (!Array.isArray(maps) ||
+        !maps.every((map) => map &&
+            typeof map.from === "string" &&
+            typeof map.to === "string")) {
+        throw new Error("Invalid directory maps");
+    }
+    for (const key of ["offset", "limit"]) {
+        if (input[key] !== undefined && !Number.isSafeInteger(input[key])) {
+            throw new Error(`Invalid ${key}`);
+        }
+    }
+    return {
+        ...(input.source !== undefined ? { sourceToken: input.source } : {}),
+        ...(input.offset !== undefined ? { offset: input.offset } : {}),
+        ...(input.limit !== undefined ? { limit: input.limit } : {}),
+        refresh: input.refresh === true,
+        match: {
+            host: input.host,
+            scope,
+            ...(project ? { project } : {}),
+            pathMaps: maps,
+        },
+    };
+}
+/** One page of session metadata; no prompts, replies, or tool data. */
+export async function listImportSessions(request, options) {
+    const source = request.sourceToken === undefined
+        ? validateImportSource(options.host, defaultImportSourcePath(options.host))
+        : null;
+    const token = source?.sourceToken ?? request.sourceToken;
+    const identity = readImportSourceToken(token, options.host);
+    const offset = Math.max(0, Math.floor(request.offset ?? 0));
+    const limit = Math.min(MAX_PAGE, Math.max(1, Math.floor(request.limit ?? 50)));
+    // A refresh takes a fresh copy of a live database; paging reuses the current one.
+    const listedAt = Date.now();
+    const matched = await matchImportSessions(identity, options, request.refresh ? "fresh" : "any");
+    const rows = [
+        ...matched.matching.map((row) => ({ ...row, selectable: true })),
+        ...(options.scope === "all-projects"
+            ? matched.unresolved.map((row) => ({ ...row, selectable: false }))
+            : []),
+    ];
+    return {
+        source: { kind: identity.kind, displayPath: identity.realPath, sourceToken: token },
+        total: rows.length,
+        offset,
+        rows: rows.slice(offset, offset + limit),
+        unresolvedCount: matched.unresolved.length,
+        revision: matched.revision,
+        listedAt,
+    };
+}
+export function validateImportSelection(value) {
+    const input = value;
+    if (!input || typeof input !== "object")
+        throw new Error("Choose sessions to import");
+    const listedAt = input.listedAt;
+    if (typeof listedAt !== "number" || !Number.isFinite(listedAt) || listedAt > Date.now()) {
+        throw new Error("Invalid listing time");
+    }
+    if (input.mode === "ids") {
+        const sessions = input.sessions;
+        if (!Array.isArray(sessions) ||
+            sessions.length === 0 ||
+            !sessions.every((item) => item &&
+                typeof item.key === "string" &&
+                typeof item.directory === "string")) {
+            throw new Error("Choose sessions to import");
+        }
+        if (sessions.length > MAX_SELECTED_KEYS) {
+            throw new Error(`Select at most ${MAX_SELECTED_KEYS} sessions one by one, or use Select all matching`);
+        }
+        return {
+            mode: "ids",
+            sessions: sessions,
+            listedAt,
+        };
+    }
+    if (input.mode === "all") {
+        const excluded = input.excludedKeys ?? [];
+        if (!Array.isArray(excluded) || !excluded.every((key) => typeof key === "string")) {
+            throw new Error("Invalid excluded sessions");
+        }
+        if (typeof input.revision !== "string")
+            throw new Error("Invalid session list revision");
+        return { mode: "all", excludedKeys: excluded, revision: input.revision, listedAt };
+    }
+    throw new Error("Choose sessions to import");
+}
+/**
+ * Re-resolve a selection against the source right before a job. New sessions
+ * make an "all" selection stale; a missing or re-projected session makes an
+ * "ids" selection stale. Neither ever imports a session the user did not see.
+ */
+export async function resolveImportSelection(sourceToken, selection, options) {
+    const identity = readImportSourceToken(sourceToken, options.host);
+    const matched = await matchImportSessions(identity, options, "reuse").catch((error) => {
+        if (error.code === "expired")
+            throw new StaleSelectionError();
+        throw error;
+    });
+    let keys;
+    if (selection.mode === "all") {
+        if (matched.revision !== selection.revision)
+            throw new StaleSelectionError();
+        const excluded = new Set(selection.excludedKeys);
+        keys = matched.matching.map((row) => row.key).filter((key) => !excluded.has(key));
+    }
+    else {
+        const current = new Map(matched.matching.map((row) => [row.key, row.directory]));
+        for (const item of selection.sessions) {
+            if (current.get(item.key) !== item.directory)
+                throw new StaleSelectionError();
+        }
+        keys = selection.sessions.map((item) => item.key);
+    }
+    if (keys.length === 0)
+        throw new Error("Choose sessions to import");
+    return { identity, keys, cutoff: selection.listedAt };
+}

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

@@ -0,0 +1,47 @@
+import type { ImportHost } from "./import-args.js";
+/**
+ * History sources chosen on the Settings page. The browser never uploads a
+ * file: it names a server-side path, the server checks it once, and later
+ * requests carry a signed token that pins the real path, device, and inode.
+ */
+export type ImportSourceKind = "pi-folder" | "pi-file" | "opencode-db";
+export interface ImportSourceIdentity {
+    host: ImportHost;
+    kind: ImportSourceKind;
+    realPath: string;
+    dev: number;
+    ino: number;
+}
+export declare class ImportSourceError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+export declare function signImportSource(identity: ImportSourceIdentity): string;
+export declare function readImportSourceToken(token: unknown, host: ImportHost): ImportSourceIdentity;
+/** Stable key for sharing snapshots and computing revisions. */
+export declare function importSourceKey(identity: ImportSourceIdentity): string;
+/** Refuse a source whose path now names another file, such as a swapped-in symlink. */
+export declare function assertImportSourceUnchanged(identity: ImportSourceIdentity): void;
+export declare function defaultImportSourcePath(host: ImportHost): string;
+export interface ValidatedImportSource {
+    kind: ImportSourceKind;
+    displayPath: string;
+    sourceToken: string;
+}
+/** Check an absolute path's kind and format; never returns file contents. */
+export declare function validateImportSource(host: ImportHost, path: unknown): ValidatedImportSource;
+export interface BrowseEntry {
+    name: string;
+    path: string;
+    kind: "folder" | "pi-file" | "opencode-db";
+}
+/**
+ * One folder at a time, with no recursion: subfolders and files the host can
+ * import. Symlinked entries are hidden. Only offered on loopback binds.
+ */
+export declare function browseImportSources(host: ImportHost, path?: unknown): {
+    path: string;
+    parent: string | null;
+    entries: BrowseEntry[];
+    truncated: boolean;
+};

package/dist/importer/import-sources.js

@@ -0,0 +1,147 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { closeSync, existsSync, openSync, readdirSync, readSync, realpathSync, statSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+import { DEFAULT_PI_SESSION_ROOT, readPiSessionHeader } from "./discovery.js";
+import { DEFAULT_OPENCODE_DB } from "./opencode-reader.js";
+export class ImportSourceError extends Error {
+    status;
+    constructor(message, status = 400) {
+        super(message);
+        this.status = status;
+        this.name = "ImportSourceError";
+    }
+}
+// Tokens only need to outlive the server process that issued them.
+const TOKEN_KEY = randomBytes(32);
+function sign(payload) {
+    return createHmac("sha256", TOKEN_KEY).update(payload).digest("base64url");
+}
+export function signImportSource(identity) {
+    const payload = Buffer.from(JSON.stringify(identity)).toString("base64url");
+    return `${payload}.${sign(payload)}`;
+}
+export function readImportSourceToken(token, host) {
+    if (typeof token !== "string")
+        throw new ImportSourceError("Choose a history source");
+    const [payload = "", signature = ""] = token.split(".");
+    const expected = Buffer.from(sign(payload));
+    const actual = Buffer.from(signature);
+    if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) {
+        throw new ImportSourceError("The history source is no longer valid. Choose it again.");
+    }
+    const identity = JSON.parse(Buffer.from(payload, "base64url").toString());
+    if (identity.host !== host)
+        throw new ImportSourceError("The source belongs to the other host");
+    return identity;
+}
+/** Stable key for sharing snapshots and computing revisions. */
+export function importSourceKey(identity) {
+    return `${identity.realPath}:${identity.dev}:${identity.ino}`;
+}
+/** Refuse a source whose path now names another file, such as a swapped-in symlink. */
+export function assertImportSourceUnchanged(identity) {
+    let current;
+    try {
+        current = statSync(identity.realPath);
+    }
+    catch {
+        throw new ImportSourceError("The history source no longer exists. Choose it again.", 409);
+    }
+    if (current.dev !== identity.dev || current.ino !== identity.ino) {
+        throw new ImportSourceError("The history source changed. Choose it again.", 409);
+    }
+}
+function checkedPath(path) {
+    if (typeof path !== "string" || !path.trim())
+        throw new ImportSourceError("Enter a path");
+    if (!isAbsolute(path))
+        throw new ImportSourceError("Enter an absolute path");
+    if (path.split(/[\\/]/).includes("..")) {
+        throw new ImportSourceError("The path must not contain '..' segments");
+    }
+    try {
+        // Symlinks at or above the chosen path are fine: macOS /tmp, a linked ~/.pi.
+        return realpathSync.native(path);
+    }
+    catch {
+        throw new ImportSourceError("Path not found");
+    }
+}
+function isSqliteFile(path) {
+    const fd = openSync(path, "r");
+    try {
+        const buffer = Buffer.alloc(16);
+        readSync(fd, buffer, 0, 16, 0);
+        return buffer.toString("latin1") === "SQLite format 3\0";
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function defaultImportSourcePath(host) {
+    return host === "pi" ? DEFAULT_PI_SESSION_ROOT : DEFAULT_OPENCODE_DB;
+}
+/** Check an absolute path's kind and format; never returns file contents. */
+export function validateImportSource(host, path) {
+    const realPath = checkedPath(path);
+    const info = statSync(realPath);
+    let kind;
+    if (host === "pi") {
+        if (info.isDirectory())
+            kind = "pi-folder";
+        else if (info.isFile() && realPath.endsWith(".jsonl")) {
+            if ("reason" in readPiSessionHeader(realPath, "")) {
+                throw new ImportSourceError("The file is not a Pi session file");
+            }
+            kind = "pi-file";
+        }
+        else
+            throw new ImportSourceError("Choose a Pi sessions folder or one .jsonl session file");
+    }
+    else {
+        if (!info.isFile() || !isSqliteFile(realPath)) {
+            throw new ImportSourceError("Choose an OpenCode database file");
+        }
+        kind = "opencode-db";
+    }
+    const identity = { host, kind, realPath, dev: info.dev, ino: info.ino };
+    return { kind, displayPath: realPath, sourceToken: signImportSource(identity) };
+}
+const BROWSE_LIMIT = 500;
+/**
+ * One folder at a time, with no recursion: subfolders and files the host can
+ * import. Symlinked entries are hidden. Only offered on loopback binds.
+ */
+export function browseImportSources(host, path) {
+    let start = path;
+    if (start === undefined || start === null || start === "") {
+        const preferred = host === "pi" ? DEFAULT_PI_SESSION_ROOT : dirname(DEFAULT_OPENCODE_DB);
+        start = existsSync(preferred) ? preferred : homedir();
+    }
+    const folder = checkedPath(start);
+    if (!statSync(folder).isDirectory())
+        throw new ImportSourceError("Choose a folder to browse");
+    const entries = [];
+    for (const entry of readdirSync(folder, { withFileTypes: true })) {
+        if (entry.isSymbolicLink())
+            continue;
+        const full = join(folder, entry.name);
+        if (entry.isDirectory())
+            entries.push({ name: entry.name, path: full, kind: "folder" });
+        else if (entry.isFile() && host === "pi" && entry.name.endsWith(".jsonl")) {
+            entries.push({ name: entry.name, path: full, kind: "pi-file" });
+        }
+        else if (entry.isFile() && host === "opencode" && entry.name.endsWith(".db")) {
+            entries.push({ name: entry.name, path: full, kind: "opencode-db" });
+        }
+    }
+    entries.sort((a, b) => Number(b.kind === "folder") - Number(a.kind === "folder") || a.name.localeCompare(b.name));
+    const parent = dirname(folder);
+    return {
+        path: folder,
+        parent: parent === folder ? null : parent,
+        entries: entries.slice(0, BROWSE_LIMIT),
+        truncated: entries.length > BROWSE_LIMIT,
+    };
+}

package/dist/importer/importer.d.ts

@@ -29,6 +29,13 @@ export interface ImportFilters {
     skipMemories?: boolean;
     pathMaps?: ImportPathMap[];
     root?: string;
+    /**
+     * Web selection: only these discovery keys (paths relative to `root`).
+     * Never combined with `session` or `maxSessions`.
+     */
+    selectionKeys?: string[];
+    /** Web selection: user turns after this epoch ms are held back for a later run. */
+    cutoff?: number;
 }
 export type ImportUnitStatus = "imported" | "would-import" | "skipped" | "failed" | "already-handled";
 export interface ImportUnitReport {
@@ -72,11 +79,16 @@ export interface ImportReport {
     projects: ImportProjectReport[];
     units: ImportUnitReport[];
     profile?: ProfileImportReport;
+    /** Turns newer than the web listing time, left for a later run. */
+    unitsHeldBack?: number;
+    /** Turns without a timestamp; date limits cannot exclude them. */
+    unitsUntimed?: number;
 }
 export interface ImporterDeps {
     loadSession: (file: string) => LoadedPiSession;
     provider: CaptureSummaryProvider;
     onProgress?: (processed: number, total: number, promptPreview: string) => void;
+    signal?: AbortSignal;
     ledger?: PiImportLedger;
     profile?: {
         model?: ModelPort;
@@ -106,6 +118,24 @@ export declare function findMemoryIdByImportId(projectHash: string, importId: st
  * /private/var) name one project, so compare through the real path.
  */
 export declare function projectFilterTag(directory: string): string;
+/**
+ * Keep the windows a run would import: inside the date range and not newer
+ * than the web listing cutoff. Held-back windows are only counted; they never
+ * reach the ledger, so a later run imports them under the same keys.
+ */
+export declare function selectImportWindows<T extends ImportWindow>(windows: T[], filters: Pick<ImportFilters, "since" | "until" | "cutoff">): {
+    kept: T[];
+    heldBack: number;
+    untimed: number;
+};
+/** Units of one session that `importHistorySource` would consider, for a counting pass. */
+export declare function countImportableUnits(session: ImportSourceSession, host: MemoryHost, filters: Pick<ImportFilters, "since" | "until">): number;
+/** Sessions produced on demand, so a large source never holds every turn at once. */
+export interface LazyImportSource {
+    /** Units that pass the date and key filters, counted in an earlier pass. */
+    total: number;
+    open: () => AsyncIterable<ImportSourceSession>;
+}
 /** Process host-labelled work units through the shared capture and ledger pipeline. */
-export declare function importHistorySource(source: AsyncIterable<ImportSourceSession> | Iterable<ImportSourceSession>, host: MemoryHost, deps: Pick<ImporterDeps, "provider" | "ledger" | "onProgress">, filters: Pick<ImportFilters, "dryRun" | "force" | "since" | "until">, report: ImportReport): Promise<void>;
+export declare function importHistorySource(source: AsyncIterable<ImportSourceSession> | Iterable<ImportSourceSession> | LazyImportSource, host: MemoryHost, deps: Pick<ImporterDeps, "provider" | "ledger" | "onProgress" | "signal">, filters: Pick<ImportFilters, "dryRun" | "force" | "since" | "until">, report: ImportReport): Promise<void>;
 export declare function importPiHistory(deps: ImporterDeps, filters: ImportFilters): Promise<ImportReport>;