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

package/dist/core/capture.js

@@ -1,3 +1,5 @@
+import { CONFIG, refreshConfigIfChanged } from "../config.js";
+import { buildCaptureAttemptRecord, emitCaptureAttempt } from "../services/capture-diagnostics.js";
 import { memoryClient } from "../services/client.js";
 import { getTags } from "../services/tags.js";
 import { buildMarkdownContext, getAutoCaptureMarkdownBudget } from "./capture-context.js";
@@ -15,7 +17,30 @@ async function getLatestProjectMemory(containerTag) {
         return null;
     }
 }
+/**
+ * Run one capture attempt and write exactly one diagnostics record for it,
+ * whether it is saved, skipped, or fails.
+ */
 export async function captureConversation(workUnit, provider) {
+    refreshConfigIfChanged(workUnit.projectDirectory);
+    const diagnostics = {};
+    const startedAt = Date.now();
+    let outcome = "failed";
+    try {
+        const result = await runCapture(workUnit, provider, diagnostics);
+        outcome = result.status === "captured" ? "saved" : "skipped";
+        return result;
+    }
+    finally {
+        const record = buildCaptureAttemptRecord({
+            host: workUnit.host,
+            sourceType: workUnit.sourceType,
+            sessionId: workUnit.hostSessionId,
+        }, diagnostics, outcome, Date.now() - startedAt);
+        emitCaptureAttempt(record, diagnostics, CONFIG);
+    }
+}
+async function runCapture(workUnit, provider, diagnostics) {
     const tags = getTags(workUnit.projectDirectory);
     const latestMemory = await getLatestProjectMemory(tags.project.tag);
     const context = buildMarkdownContext(workUnit.userPrompt, workUnit.textResponses, workUnit.toolCalls, latestMemory, getAutoCaptureMarkdownBudget());
@@ -27,9 +52,11 @@ export async function captureConversation(workUnit, provider) {
             projectDirectory: workUnit.projectDirectory,
             userPrompt: workUnit.userPrompt,
             prompt: workUnit.prompt,
+            diagnostics,
         });
     }
     catch (error) {
+        diagnostics.failureReason ??= "call-error";
         const message = error instanceof Error ? error.message : String(error);
         throw new Error(`Summary generation failed: ${message}`, { cause: error });
     }
@@ -40,6 +67,8 @@ export async function captureConversation(workUnit, provider) {
         ? `${summaryResult.summary}\n\nTags: ${summaryResult.tags.join(", ")}`
         : summaryResult.summary;
     const source = workUnit.sourceType === "history-import" ? "import" : "auto-capture";
+    // Anything that goes wrong from here on is a storage failure, thrown or reported.
+    diagnostics.failureReason = "persist-error";
     const result = await memoryClient.addMemory(summaryWithTags, tags.project.tag, {
         source,
         type: summaryResult.type,
@@ -64,5 +93,6 @@ export async function captureConversation(workUnit, provider) {
     if (!result.success) {
         throw new Error(`Memory persistence failed: ${result.error || "database write failed"}`);
     }
+    diagnostics.failureReason = undefined;
     return { status: "captured", memoryId: result.id };
 }

package/dist/core/extraction.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { CaptureSummary } from "./host.js";
+import type { CaptureFailureReason, CaptureSummary } from "./host.js";
 /**
  * Shared structured-extraction contract for automatic capture.
  *
@@ -38,6 +38,13 @@ export declare const captureSummaryToolSchema: {
     };
     required: string[];
 };
+/**
+ * Reply-format instruction for paths that get plain text back (the Pi model
+ * bridge). Structured-output and tool-call paths enforce the shape themselves,
+ * so without this the model only sees the Markdown layout of the summary field
+ * and `type="skip"`, and tends to answer in that form instead of JSON.
+ */
+export declare function buildCaptureReplyInstruction(): string;
 export declare function buildCaptureSystemPrompt(languageName: string): string;
 /** Upper bound for LLM-inferred preference confidence (0–1 scale). */
 export declare const USER_PROFILE_LLM_CONFIDENCE_MAX = 1;
@@ -78,3 +85,18 @@ export declare function extractJsonObject(raw: string): unknown;
  * blocks and surrounding prose. Returns null when no valid payload is present.
  */
 export declare function parseCaptureSummary(raw: string): CaptureSummary | null;
+/**
+ * Map provider-specific stop reasons onto one vocabulary so a length limit
+ * reads as `length` on every extraction path. Other values pass through in
+ * lower case.
+ */
+export declare function normalizeStopReason(stopReason: string | null | undefined): string | undefined;
+/**
+ * Explain why a reply is not a usable capture summary. Returns null when the
+ * reply parses (including a skip). Codes are checked in the spec's order, so a
+ * cut-off reply reads as `truncated` rather than `invalid-json`.
+ */
+export declare function classifyCaptureReply(reply: {
+    text: string;
+    stopReason?: string | null;
+}): CaptureFailureReason | null;

package/dist/core/extraction.js

@@ -40,6 +40,18 @@ export const captureSummaryToolSchema = {
     },
     required: ["summary", "type", "tags"],
 };
+/**
+ * Reply-format instruction for paths that get plain text back (the Pi model
+ * bridge). Structured-output and tool-call paths enforce the shape themselves,
+ * so without this the model only sees the Markdown layout of the summary field
+ * and `type="skip"`, and tends to answer in that form instead of JSON.
+ */
+export function buildCaptureReplyInstruction() {
+    return `Reply with only one JSON object and nothing else: no prose, no code fence. It must match this JSON schema:
+${JSON.stringify(captureSummaryToolSchema)}
+Put the Markdown summary (## Request / ## Outcome) inside the "summary" string.
+For a non-technical conversation reply exactly: {"type":"skip","summary":"","tags":[]}`;
+}
 export function buildCaptureSystemPrompt(languageName) {
     return `You are a technical memory recorder for a software development project.
 
@@ -143,3 +155,32 @@ export function parseCaptureSummary(raw) {
         tags: parsed.data.tags.map((tag) => tag.toLowerCase().trim()).filter(Boolean),
     };
 }
+const LENGTH_STOP_REASONS = new Set(["length", "max_tokens", "max_output_tokens"]);
+/**
+ * Map provider-specific stop reasons onto one vocabulary so a length limit
+ * reads as `length` on every extraction path. Other values pass through in
+ * lower case.
+ */
+export function normalizeStopReason(stopReason) {
+    if (!stopReason)
+        return undefined;
+    const lower = stopReason.toLowerCase();
+    return LENGTH_STOP_REASONS.has(lower) ? "length" : lower;
+}
+/**
+ * Explain why a reply is not a usable capture summary. Returns null when the
+ * reply parses (including a skip). Codes are checked in the spec's order, so a
+ * cut-off reply reads as `truncated` rather than `invalid-json`.
+ */
+export function classifyCaptureReply(reply) {
+    if (parseCaptureSummary(reply.text))
+        return null;
+    if (reply.text.trim().length === 0)
+        return "empty-text";
+    if (normalizeStopReason(reply.stopReason) === "length")
+        return "truncated";
+    const json = extractJsonObject(reply.text);
+    if (json === null || typeof json !== "object" || Array.isArray(json))
+        return "invalid-json";
+    return "schema-mismatch";
+}

package/dist/core/host.d.ts

@@ -19,12 +19,35 @@ export interface CaptureSummary {
     type: string;
     tags: string[];
 }
+export type CaptureAttemptOutcome = "saved" | "skipped" | "failed";
+/** Fixed failure codes, in the order classification checks them. */
+export declare const CAPTURE_FAILURE_REASONS: readonly ["call-error", "empty-text", "truncated", "invalid-json", "schema-mismatch", "persist-error"];
+export type CaptureFailureReason = (typeof CAPTURE_FAILURE_REASONS)[number];
+export type CaptureExtractionPath = "host-model" | "external-api";
+/**
+ * Filled in by the extraction path during one capture attempt. The capture
+ * pipeline owns the object and emits it once the outcome is known. Fields a
+ * path cannot observe stay undefined. The prompt and reply fields are only
+ * ever written to the opt-in trace file, never to the log.
+ */
+export interface CaptureAttemptDiagnostics {
+    path?: CaptureExtractionPath;
+    provider?: string;
+    model?: string;
+    stopReason?: string;
+    blockTypes?: string[];
+    systemPrompt?: string;
+    userPrompt?: string;
+    rawReply?: string;
+    failureReason?: CaptureFailureReason;
+}
 export interface CaptureSummaryRequest {
     context: string;
     sessionId: string;
     projectDirectory: string;
     userPrompt: string;
     prompt?: CapturePromptContext;
+    diagnostics?: CaptureAttemptDiagnostics;
 }
 export interface CaptureSummaryProvider {
     summarize(request: CaptureSummaryRequest): Promise<CaptureSummary | null>;

package/dist/core/host.js

@@ -1 +1,9 @@
-export {};
+/** Fixed failure codes, in the order classification checks them. */
+export const CAPTURE_FAILURE_REASONS = [
+    "call-error",
+    "empty-text",
+    "truncated",
+    "invalid-json",
+    "schema-mismatch",
+    "persist-error",
+];

package/dist/core/profile-analysis.js

@@ -10,7 +10,15 @@ CRITICAL: Detect the language used by the user in their prompts. You MUST output
 
 CRITICAL: All JSON string values MUST escape double quotes with backslash. Do NOT use unescaped quotation marks inside string values.
 
-Respond with a single JSON object matching the update_user_profile contract.`;
+Respond with one JSON object. It must have these required fields:
+{
+  "preferences": [{ "category": "string", "description": "string", "confidence": 0.8, "evidence": ["string"] }],
+  "patterns": [{ "category": "string", "description": "string" }],
+  "workflows": [{ "description": "string", "steps": ["string"] }]
+}
+Use an empty array for a field with no findings. Confidence must be a number from 0 to 1.
+If you include "validations", each entry needs a numeric "index", a string "reason", and a "verdict" of "confirmed", "contradicted", "no_evidence", "inaccurate", or "oversimplified".
+Return JSON only, without Markdown or other text.`;
 }
 /** Analyse prompts with a host-neutral model and merge the validated profile. */
 export async function analyzeProfile(model, context, existingProfile, timeoutMs = 120000) {

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;