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

package/dist/config.d.ts

@@ -23,7 +23,7 @@ interface OmmsConfig {
     autoCaptureMaxRetries?: number;
     autoCaptureMaxContextBytes?: number;
     autoCaptureLanguage?: string;
-    memoryProvider?: "openai-chat" | "openai-responses" | "anthropic" | "minimax" | "orcarouter";
+    memoryProvider?: "openai-chat" | "openai-responses" | "anthropic" | "minimax" | "orcarouter" | "google-gemini";
     memoryModel?: string;
     memoryApiUrl?: string;
     memoryApiKey?: string;
@@ -45,6 +45,11 @@ interface OmmsConfig {
     autoBackfill?: boolean;
     opencodeBackfillModel?: string;
     piBackfillModel?: string;
+    /** Saved directory maps for every history import. Global config only. */
+    importPathMaps?: Array<{
+        from: string;
+        to: string;
+    }>;
     webServerAutoStart?: boolean;
     webServerEnabled?: boolean;
     webServerPort?: number;
@@ -93,7 +98,7 @@ interface OmmsConfig {
         injectOn?: "first" | "always";
     };
 }
-export declare const CONFIG_TEMPLATE = "{\n  // ============================================\n  // omms (Opinionated Modular Memory System) Configuration\n  // ============================================\n  \n  // Storage location for the vector database. Leave unset to use the\n  // default ~/.omms/data (a legacy ~/.opencode-mem/data store is migrated\n  // there automatically on first start; see docs/omms-migration.md).\n  // \"storagePath\": \"~/.omms/data\",\n\n  \"userEmailOverride\": \"\",\n  \"userNameOverride\": \"\",\n  \n  // ============================================\n  // Embedding Model (for similarity search)\n  // ============================================\n  // Local = Hugging Face / ONNX via @huggingface/transformers (not Apple MLX).\n  // Remote = set BOTH embeddingApiUrl and embeddingApiKey (OpenAI-compatible /embeddings).\n  \n  // Default: Nomic Embed v1 (768 dimensions, 8192 context, multilingual)\n  \"embeddingModel\": \"Xenova/nomic-embed-text-v1\",\n\n  // Opt-in Nomic task prefixes (search_document: / search_query:). After enabling,\n  // re-index existing memories so store and query vectors stay aligned.\n  // \"embeddingUseTaskPrefixes\": true,\n  \n  // Auto-detected dimensions (no need to set manually)\n  // \"embeddingDimensions\": 768,\n  \n  // Other recommended local models:\n  // \"embeddingModel\": \"Xenova/jina-embeddings-v2-base-en\",  // 768 dims, English-only, 8192 context\n  // \"embeddingModel\": \"Xenova/jina-embeddings-v2-small-en\", // 512 dims, faster, 8192 context\n  // \"embeddingModel\": \"Xenova/all-MiniLM-L6-v2\",            // 384 dims, very fast, 512 context\n  // \"embeddingModel\": \"Xenova/all-mpnet-base-v2\",           // 768 dims, good quality, 512 context\n  \n  // Optional: OpenAI-compatible API for embeddings (both URL and key required)\n  // \"embeddingApiUrl\": \"https://api.openai.com/v1\",\n  // \"embeddingApiKey\": \"env://OPENAI_API_KEY\",  // or \"sk-...\" / \"file:///path/to/key\"\n  // \"embeddingModel\": \"text-embedding-3-small\",  // 1536 dims, auto-detected\n \n  // ============================================\n  // Web Server Settings\n  // ============================================\n  \n  // Start a background import of past chats on each host's next start.\n  \"autoBackfill\": true,\n  // \"piBackfillModel\": \"inherit\", // or \"provider/model\"\n  // \"opencodeBackfillModel\": \"inherit\", // or \"provider/model\"\n\n  // Register the web app to start when you log in.\n  \"webServerAutoStart\": true,\n  // Enable web UI for managing memories (accessible at http://localhost:4747)\n  \"webServerEnabled\": true,\n  \n  // Port for web UI server\n  \"webServerPort\": 4747,\n  \n  // Host address for web UI (use 127.0.0.1 for local only, 0.0.0.0 for network access)\n  \"webServerHost\": \"127.0.0.1\",\n\n  // Optional HTTP Basic Auth for the web UI. Accepts literal, env://, or file:// secrets.\n  // \"webServerAuthPassword\": \"\",\n  // \"webServerAuthUsername\": \"\",\n\n  // Required when webServerHost is not loopback. Protects /api/* with Bearer / X-Opencode-Mem-Token.\n  // \"webServerApiToken\": \"env://OMMS_WEB_TOKEN\",\n  \n  // ============================================\n  // Database Settings\n  // ============================================\n  \n  // Maximum vectors per database shard (auto-creates new shard when limit reached)\n  \"maxVectorsPerShard\": 50000,\n  \n  // Automatically delete old memories based on retention period\n  \"autoCleanupEnabled\": true,\n  \n  // Days to keep memories before auto-cleanup (only if autoCleanupEnabled is true)\n  \"autoCleanupRetentionDays\": 30,\n  \n  // Automatically detect and remove duplicate memories\n  \"deduplicationEnabled\": true,\n  \n   // Similarity threshold (0-1) for detecting duplicates (higher = stricter)\n   \"deduplicationSimilarityThreshold\": 0.90,\n   \n  // ============================================\n  // Memory Scope Settings\n  // ============================================\n\n  // Default scope for memory list/search queries\n  // \"project\" keeps queries within the current project, \"all-projects\" searches across all project shards\n  \"memory\": {\n    \"defaultScope\": \"project\"\n  },\n\n  // ============================================\n  // Model for auto-capture and profile learning (same rule in OpenCode and Pi)\n  // ============================================\n\n   // Which model summarises your work, in this order:\n   //   1. The host model below: opencodeProvider/opencodeModel in OpenCode,\n   //      piProvider/piModel in Pi. Set the model to \"inherit\" to follow\n   //      whatever model the session is using.\n   //   2. If no host model is set: the external API (memoryModel/memoryApiUrl/\n   //      memoryApiKey further down).\n   //   3. If neither is set: the session's own model.\n   // If the host model fails and the external API is configured, the external\n   // API is used instead.\n   //\n   // Host models go through OpenCode's or Pi's own sign-in (OAuth like Claude\n   // Pro/Max, GitHub Copilot, ChatGPT, or your own key there), so no separate API\n   // key is needed here.\n   //\n   // Examples (OpenCode names from 'opencode providers list'; Pi names from its model list):\n   //   \"opencodeProvider\": \"anthropic\",    \"opencodeModel\": \"claude-haiku-4-5-20251001\"\n   //   \"opencodeProvider\": \"openai\",       \"opencodeModel\": \"inherit\"\n   //   \"piProvider\": \"openai-codex\",       \"piModel\": \"gpt-5.6-luna\"\n   //\n   // \"opencodeProvider\": \"anthropic\",\n   // \"opencodeModel\": \"claude-haiku-4-5-20251001\",\n   // \"piProvider\": \"openai-codex\",\n   // \"piModel\": \"gpt-5.6-luna\",\n\n   // ============================================\n   // Auto-Capture Settings\n   // ============================================\n  \n  // Auto-capture runs in the background without blocking your main session.\n  // Note: Ollama may not support tool calling. Use OpenAI, Anthropic, or Groq for best results.\n  \n  \"autoCaptureEnabled\": true,\n  \n  // Provider type: \"openai-chat\" | \"openai-responses\" | \"anthropic\" | \"minimax\" | \"orcarouter\"\n  // Note: \"openai-chat\" is a generic OpenAI API-compatible mode.\n  // Any service that follows the OpenAI Chat Completions API can use it via custom \"memoryApiUrl\".\n  \"memoryProvider\": \"openai-chat\",\n  \n  // External API (step 2 above, and the fallback when a host model fails).\n  // Uncomment all 3 lines and replace memoryApiKey before use:\n  // \"memoryModel\": \"gpt-4o-mini\",\n  // \"memoryApiUrl\": \"https://api.openai.com/v1\",\n  // \"memoryApiKey\": \"sk-...\",\n\n  // API Key Formats:\n  // Direct value:        \"sk-...\"\n  // From file:           \"file://~/.config/litellm-key.txt\"\n  // From env variable:   \"env://LITELLM_API_KEY\"\n  \n  // Examples for different providers:\n  // Any OpenAI-compatible endpoint can use the \"openai-chat\" provider pattern below.\n  // Common examples: DeepSeek, Qwen (via Alibaba Cloud ModelStudio),\n  // Zhipu GLM (BigModel platform), and Kimi (Moonshot AI platform).\n\n  // OpenAI Chat Completion (default, backward compatible):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"gpt-4o-mini\"\n  //   \"memoryApiUrl\": \"https://api.openai.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n\n  // DeepSeek (OpenAI-compatible example):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"deepseek-chat\"\n  //   \"memoryApiUrl\": \"https://api.deepseek.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n  \n  // OpenAI Responses API (recommended, with session support):\n  //   \"memoryProvider\": \"openai-responses\"\n  //   \"memoryModel\": \"gpt-4o\"\n  //   \"memoryApiUrl\": \"https://api.openai.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n  \n  // Anthropic (with session support):\n  //   \"memoryProvider\": \"anthropic\"\n  //   \"memoryModel\": \"claude-3-5-haiku-20241022\"\n  //   \"memoryApiUrl\": \"https://api.anthropic.com/v1\"\n  //   \"memoryApiKey\": \"sk-ant-...\"\n\n  // MiniMax (Anthropic Messages-compatible endpoint, with session support):\n  //   \"memoryProvider\": \"minimax\"\n  //   \"memoryModel\": \"MiniMax-M3\"\n  //   \"memoryApiUrl\": \"https://api.minimax.io\"        // global endpoint\n  //   \"memoryApiKey\": \"<MiniMax API key>\"\n  //   // China endpoint: \"memoryApiUrl\": \"https://api.minimaxi.com\"\n  //   // Optional adaptive thinking for MiniMax-M3:\n  //   \"memoryExtraParams\": { \"thinking\": { \"type\": \"adaptive\" } }\n\n  // OrcaRouter (OpenAI-compatible gateway, namespaced model IDs, with session support):\n  //   \"memoryProvider\": \"orcarouter\"\n  //   \"memoryApiKey\": \"<OrcaRouter API key>\"\n  //   // memoryApiUrl and memoryModel are optional \u2014 they default to\n  //   // https://api.orcarouter.ai/v1 and \"orcarouter/auto\" (a routing alias).\n  //   // OrcaRouter rejects bare model names, so if you set memoryModel, use a\n  //   // namespaced ID such as \"openai/gpt-5.5\" or \"deepseek/deepseek-v4-flash\".\n  //   \"memoryModel\": \"openai/gpt-5.5\"\n\n  // Groq (OpenAI-compatible, use openai-chat provider):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"llama-3.3-70b-versatile\"\n  //   \"memoryApiUrl\": \"https://api.groq.com/openai/v1\"\n  //   \"memoryApiKey\": \"gsk_...\"\n  \n  // Maximum iterations for multi-turn AI analysis (for openai-responses, anthropic, and minimax)\n  \"autoCaptureMaxIterations\": 5,\n   \n  // Timeout per iteration in milliseconds (30 seconds default)\n  \"autoCaptureIterationTimeout\": 30000,\n\n  // Maximum number of times to retry capturing a prompt if it fails (due to network, API errors, etc.)\n  \"autoCaptureMaxRetries\": 3,\n\n  // Maximum UTF-8 bytes for the auto-capture markdown context sent to the summary model.\n  // Prevents HTTP 400 context overflows on models with ~131K token windows (e.g. Groq Llama).\n  // Rough guide: tokens \u2248 bytes / 4 for mixed code/prose.\n  \"autoCaptureMaxContextBytes\": 131072,\n   \n  // Days to keep AI session history before cleanup\n  \"aiSessionRetentionDays\": 7,\n\n  // Capture diagnostics: every capture attempt always writes one metadata line\n  // (model, stop reason, sizes, outcome) to ~/.omms/omms.log, with no\n  // conversation text. Set captureTrace to true to also write each attempt's\n  // prompt and raw reply to ~/.omms/traces/ for debugging. Traces can contain\n  // conversation content: <private> text and common API key formats are\n  // redacted, files are readable only by you, and they are deleted after\n  // captureTraceRetentionDays. Only this global file can turn tracing on.\n  // \"captureTrace\": false,\n  // \"captureTraceRetentionDays\": 7,\n  // \"captureAttemptRetentionDays\": 30,\n\n  // Temperature for AI API requests (set to false to omit parameter for models that don't support it)\n  // Some reasoning models (like o1, o3, gpt-5) don't support temperature parameter\n  // Set to false and add \"memoryTemperature\": false in config when using such models\n  \"memoryTemperature\": 0.3,\n\n  // Extra parameters to include in API request body\n  // Useful for local inference servers (e.g. llama-server with --jinja) that support\n  // additional parameters like disabling thinking/reasoning mode\n  // Example for Qwen3 models: { \"enable_thinking\": false }\n  // \"memoryExtraParams\": {},\n\n  // Language for auto-capture summaries (default: \"auto\" for auto-detection)\n  // Options: \"auto\", \"en\", \"id\", \"zh\", \"ja\", \"es\", \"fr\", \"de\", \"ru\", \"pt\", \"ar\", \"ko\"\n  // \"autoCaptureLanguage\": \"auto\",\n\n  // ============================================\n  // Toast Notifications\n  // ============================================\n\n  // Show toast when memory is auto-captured\n  \"showAutoCaptureToasts\": true,\n\n  // Show toast when user profile is updated\n  \"showUserProfileToasts\": true,\n\n  // Show toast for error messages\n  \"showErrorToasts\": true,\n\n  // ============================================\n  // User Profile System\n  // ============================================\n\n  // Analyze user prompts every N prompts to build/update your user profile\n  // When N uncaptured prompts accumulate, AI will analyze them to identify:\n  // - User preferences (code style, communication style, tool preferences)\n  // - User patterns (recurring topics, problem domains, technical interests)\n  // - User workflows (development habits, sequences, learning style)\n  // - Skill level (overall and per-domain assessment)\n  \"userProfileAnalysisInterval\": 10,\n\n  // Days before inactive items (all types) are eligible for removal\n  \"userProfileStaleDays\": 2,\n\n  // Number of preferences shown in UI\n  \"userProfileDisplayPreferences\": 20,\n  \n  // Number of patterns shown in UI\n  \"userProfileDisplayPatterns\": 15,\n  \n  // Number of workflows shown in UI\n  \"userProfileDisplayWorkflows\": 10,\n  \n  // Number of preferences injected into LLM conversation context\n  // Keep this small \u2014 the strongest signals are enough; more dilute LLM attention\n  \"userProfileInjectPreferences\": 5,\n  \n  // Number of patterns injected into LLM conversation context\n  \"userProfileInjectPatterns\": 5,\n  \n  // Number of workflows injected into LLM conversation context\n  \"userProfileInjectWorkflows\": 3,\n  \n  // Days before preference confidence starts to decay (if not reinforced)\n  // Preferences that aren't seen again will gradually lose confidence and be removed\n  \"userProfileConfidenceDecayDays\": 30,\n  \n  // Number of profile versions to keep in changelog (for rollback/debugging)\n  // Older versions are automatically cleaned up\n  \"userProfileChangelogRetentionCount\": 5,\n\n  // Minimum evidence count for a preference/pattern to survive confidence decay\n  // Items confirmed fewer times are more likely to be pruned when confidence decays\n  \"userProfileMinEvidenceForRetention\": 3,\n\n  // Periodically merge duplicate or irrelevant profile items with the configured AI provider\n  \"userProfileAutoCleanupEnabled\": true,\n  // Number of analyzed user prompts between automatic AI cleanup runs\n  \"userProfileAutoCleanupInterval\": 100,\n\n  // Enable LLM validation of existing preferences against recent behavior.\n  // When enabled, each analysis round checks if top-5 preferences still match recent prompts.\n  // Experimental \u2014 disabled by default.\n  \"userProfileValidationEnabled\": false,\n\n  // ============================================\n  // Search Settings\n  // ============================================\n  \n  // Minimum similarity score (0-1) for memory search results\n  \"similarityThreshold\": 0.6,\n\n  // Maximum number of memories to return in search results\n  \"maxMemories\": 10,\n\n  // ============================================\n  // Advanced Settings\n  // ============================================\n  \n  // Inject user profile into AI context (preferences, patterns, workflows)\n  \"injectProfile\": true\n}\n";
+export declare const CONFIG_TEMPLATE = "{\n  // ============================================\n  // omms (Opinionated Modular Memory System) Configuration\n  // ============================================\n  \n  // Storage location for the vector database. Leave unset to use the\n  // default ~/.omms/data (a legacy ~/.opencode-mem/data store is migrated\n  // there automatically on first start; see docs/omms-migration.md).\n  // \"storagePath\": \"~/.omms/data\",\n\n  \"userEmailOverride\": \"\",\n  \"userNameOverride\": \"\",\n  \n  // ============================================\n  // Embedding Model (for similarity search)\n  // ============================================\n  // Local = Hugging Face / ONNX via @huggingface/transformers (not Apple MLX).\n  // Remote = set BOTH embeddingApiUrl and embeddingApiKey (OpenAI-compatible /embeddings).\n  \n  // Default: Nomic Embed v1 (768 dimensions, 8192 context, multilingual)\n  \"embeddingModel\": \"Xenova/nomic-embed-text-v1\",\n\n  // Opt-in Nomic task prefixes (search_document: / search_query:). After enabling,\n  // re-index existing memories so store and query vectors stay aligned.\n  // \"embeddingUseTaskPrefixes\": true,\n  \n  // Auto-detected dimensions (no need to set manually)\n  // \"embeddingDimensions\": 768,\n  \n  // Other recommended local models:\n  // \"embeddingModel\": \"Xenova/jina-embeddings-v2-base-en\",  // 768 dims, English-only, 8192 context\n  // \"embeddingModel\": \"Xenova/jina-embeddings-v2-small-en\", // 512 dims, faster, 8192 context\n  // \"embeddingModel\": \"Xenova/all-MiniLM-L6-v2\",            // 384 dims, very fast, 512 context\n  // \"embeddingModel\": \"Xenova/all-mpnet-base-v2\",           // 768 dims, good quality, 512 context\n  \n  // Optional: OpenAI-compatible API for embeddings (both URL and key required)\n  // \"embeddingApiUrl\": \"https://api.openai.com/v1\",\n  // \"embeddingApiKey\": \"env://OPENAI_API_KEY\",  // or \"sk-...\" / \"file:///path/to/key\"\n  // \"embeddingModel\": \"text-embedding-3-small\",  // 1536 dims, auto-detected\n \n  // ============================================\n  // Web Server Settings\n  // ============================================\n  \n  // Start a background import of past chats on each host's next start.\n  \"autoBackfill\": true,\n  // \"piBackfillModel\": \"inherit\", // or \"external\", or \"provider/model\"\n  // \"opencodeBackfillModel\": \"inherit\", // or \"external\", or \"provider/model\"\n  // Directory maps for history recorded in moved or deleted directories.\n  // \"importPathMaps\": [{ \"from\": \"~/code/app-feat-x\", \"to\": \"~/code/app\" }],\n\n  // Register the web app to start when you log in.\n  \"webServerAutoStart\": true,\n  // Enable web UI for managing memories (accessible at http://localhost:4747)\n  \"webServerEnabled\": true,\n  \n  // Port for web UI server\n  \"webServerPort\": 4747,\n  \n  // Host address for web UI (use 127.0.0.1 for local only, 0.0.0.0 for network access)\n  \"webServerHost\": \"127.0.0.1\",\n\n  // Optional HTTP Basic Auth for the web UI. Accepts literal, env://, or file:// secrets.\n  // \"webServerAuthPassword\": \"\",\n  // \"webServerAuthUsername\": \"\",\n\n  // Required when webServerHost is not loopback. Protects /api/* with Bearer / X-Omms-Token (legacy X-Opencode-Mem-Token still works).\n  // \"webServerApiToken\": \"env://OMMS_WEB_TOKEN\",\n  \n  // ============================================\n  // Database Settings\n  // ============================================\n  \n  // Maximum vectors per database shard (auto-creates new shard when limit reached)\n  \"maxVectorsPerShard\": 50000,\n  \n  // Automatically delete old memories based on retention period\n  \"autoCleanupEnabled\": true,\n  \n  // Days to keep memories before auto-cleanup (only if autoCleanupEnabled is true)\n  \"autoCleanupRetentionDays\": 30,\n  \n  // Automatically detect and remove duplicate memories\n  \"deduplicationEnabled\": true,\n  \n   // Similarity threshold (0-1) for detecting duplicates (higher = stricter)\n   \"deduplicationSimilarityThreshold\": 0.90,\n   \n  // ============================================\n  // Memory Scope Settings\n  // ============================================\n\n  // Default scope for memory list/search queries\n  // \"project\" keeps queries within the current project, \"all-projects\" searches across all project shards\n  \"memory\": {\n    \"defaultScope\": \"project\"\n  },\n\n  // ============================================\n  // Model for auto-capture and profile learning (same rule in OpenCode and Pi)\n  // ============================================\n\n   // Which model summarises your work, in this order:\n   //   1. The host model below: opencodeProvider/opencodeModel in OpenCode,\n   //      piProvider/piModel in Pi. Set the model to \"inherit\" to follow\n   //      whatever model the session is using, or to \"external\" to send\n   //      every call to the external API below.\n   //   2. If no host model is set: the external API (memoryModel/memoryApiUrl/\n   //      memoryApiKey further down).\n   //   3. If neither is set: the session's own model.\n   // If the host model fails and the external API is configured, the external\n   // API is used instead.\n   //\n   // Host models go through OpenCode's or Pi's own sign-in (OAuth like Claude\n   // Pro/Max, GitHub Copilot, ChatGPT, or your own key there), so no separate API\n   // key is needed here.\n   //\n   // Examples (OpenCode names from 'opencode providers list'; Pi names from its model list):\n   //   \"opencodeProvider\": \"anthropic\",    \"opencodeModel\": \"claude-haiku-4-5-20251001\"\n   //   \"opencodeProvider\": \"openai\",       \"opencodeModel\": \"inherit\"\n   //   \"piProvider\": \"openai-codex\",       \"piModel\": \"gpt-5.6-luna\"\n   //\n   // \"opencodeProvider\": \"anthropic\",\n   // \"opencodeModel\": \"claude-haiku-4-5-20251001\",\n   // \"piProvider\": \"openai-codex\",\n   // \"piModel\": \"gpt-5.6-luna\",\n\n   // ============================================\n   // Auto-Capture Settings\n   // ============================================\n  \n  // Auto-capture runs in the background without blocking your main session.\n  // Note: Ollama may not support tool calling. Use OpenAI, Anthropic, or Groq for best results.\n  \n  \"autoCaptureEnabled\": true,\n  \n  // Provider type: \"openai-chat\" | \"openai-responses\" | \"anthropic\" | \"minimax\" | \"orcarouter\" | \"google-gemini\"\n  // Note: \"openai-chat\" is a generic OpenAI API-compatible mode.\n  // Any service that follows the OpenAI Chat Completions API can use it via custom \"memoryApiUrl\".\n  \"memoryProvider\": \"openai-chat\",\n  \n  // External API (step 2 above, and the fallback when a host model fails).\n  // Uncomment all 3 lines and replace memoryApiKey before use:\n  // \"memoryModel\": \"gpt-4o-mini\",\n  // \"memoryApiUrl\": \"https://api.openai.com/v1\",\n  // \"memoryApiKey\": \"sk-...\",\n\n  // API Key Formats:\n  // Direct value:        \"sk-...\"\n  // From file:           \"file://~/.config/litellm-key.txt\"\n  // From env variable:   \"env://LITELLM_API_KEY\"\n  \n  // Examples for different providers:\n  // Any OpenAI-compatible endpoint can use the \"openai-chat\" provider pattern below.\n  // Common examples: DeepSeek, Qwen (via Alibaba Cloud ModelStudio),\n  // Zhipu GLM (BigModel platform), and Kimi (Moonshot AI platform).\n\n  // OpenAI Chat Completion (default, backward compatible):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"gpt-4o-mini\"\n  //   \"memoryApiUrl\": \"https://api.openai.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n\n  // DeepSeek (OpenAI-compatible example):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"deepseek-chat\"\n  //   \"memoryApiUrl\": \"https://api.deepseek.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n  \n  // OpenAI Responses API (recommended, with session support):\n  //   \"memoryProvider\": \"openai-responses\"\n  //   \"memoryModel\": \"gpt-4o\"\n  //   \"memoryApiUrl\": \"https://api.openai.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n  \n  // Anthropic (with session support):\n  //   \"memoryProvider\": \"anthropic\"\n  //   \"memoryModel\": \"claude-3-5-haiku-20241022\"\n  //   \"memoryApiUrl\": \"https://api.anthropic.com/v1\"\n  //   \"memoryApiKey\": \"sk-ant-...\"\n\n  // MiniMax (Anthropic Messages-compatible endpoint, with session support):\n  //   \"memoryProvider\": \"minimax\"\n  //   \"memoryModel\": \"MiniMax-M3\"\n  //   \"memoryApiUrl\": \"https://api.minimax.io\"        // global endpoint\n  //   \"memoryApiKey\": \"<MiniMax API key>\"\n  //   // China endpoint: \"memoryApiUrl\": \"https://api.minimaxi.com\"\n  //   // Optional adaptive thinking for MiniMax-M3:\n  //   \"memoryExtraParams\": { \"thinking\": { \"type\": \"adaptive\" } }\n\n  // OrcaRouter (OpenAI-compatible gateway, namespaced model IDs, with session support):\n  //   \"memoryProvider\": \"orcarouter\"\n  //   \"memoryApiKey\": \"<OrcaRouter API key>\"\n  //   // memoryApiUrl and memoryModel are optional \u2014 they default to\n  //   // https://api.orcarouter.ai/v1 and \"orcarouter/auto\" (a routing alias).\n  //   // OrcaRouter rejects bare model names, so if you set memoryModel, use a\n  //   // namespaced ID such as \"openai/gpt-5.5\" or \"deepseek/deepseek-v4-flash\".\n  //   \"memoryModel\": \"openai/gpt-5.5\"\n\n  // Groq (OpenAI-compatible, use openai-chat provider):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"llama-3.3-70b-versatile\"\n  //   \"memoryApiUrl\": \"https://api.groq.com/openai/v1\"\n  //   \"memoryApiKey\": \"gsk_...\"\n  \n  // Maximum iterations for multi-turn AI analysis (for openai-responses, anthropic, and minimax)\n  \"autoCaptureMaxIterations\": 5,\n   \n  // Timeout per iteration in milliseconds (30 seconds default)\n  \"autoCaptureIterationTimeout\": 30000,\n\n  // Maximum number of times to retry capturing a prompt if it fails (due to network, API errors, etc.)\n  \"autoCaptureMaxRetries\": 3,\n\n  // Maximum UTF-8 bytes for the auto-capture markdown context sent to the summary model.\n  // Prevents HTTP 400 context overflows on models with ~131K token windows (e.g. Groq Llama).\n  // Rough guide: tokens \u2248 bytes / 4 for mixed code/prose.\n  \"autoCaptureMaxContextBytes\": 131072,\n   \n  // Days to keep AI session history before cleanup\n  \"aiSessionRetentionDays\": 7,\n\n  // Capture diagnostics: every capture attempt always writes one metadata line\n  // (model, stop reason, sizes, outcome) to ~/.omms/omms.log, with no\n  // conversation text. Set captureTrace to true to also write each attempt's\n  // prompt and raw reply to ~/.omms/traces/ for debugging. Traces can contain\n  // conversation content: <private> text and common API key formats are\n  // redacted, files are readable only by you, and they are deleted after\n  // captureTraceRetentionDays. Only this global file can turn tracing on.\n  // \"captureTrace\": false,\n  // \"captureTraceRetentionDays\": 7,\n  // \"captureAttemptRetentionDays\": 30,\n\n  // Temperature for AI API requests (set to false to omit parameter for models that don't support it)\n  // Some reasoning models (like o1, o3, gpt-5) don't support temperature parameter\n  // Set to false and add \"memoryTemperature\": false in config when using such models\n  \"memoryTemperature\": 0.3,\n\n  // Extra parameters to include in API request body\n  // Useful for local inference servers (e.g. llama-server with --jinja) that support\n  // additional parameters like disabling thinking/reasoning mode\n  // Example for Qwen3 models: { \"enable_thinking\": false }\n  // \"memoryExtraParams\": {},\n\n  // Language for auto-capture summaries (default: \"auto\" for auto-detection)\n  // Options: \"auto\", \"en\", \"id\", \"zh\", \"ja\", \"es\", \"fr\", \"de\", \"ru\", \"pt\", \"ar\", \"ko\"\n  // \"autoCaptureLanguage\": \"auto\",\n\n  // ============================================\n  // Toast Notifications\n  // ============================================\n\n  // Show toast when memory is auto-captured\n  \"showAutoCaptureToasts\": true,\n\n  // Show toast when user profile is updated\n  \"showUserProfileToasts\": true,\n\n  // Show toast for error messages\n  \"showErrorToasts\": true,\n\n  // ============================================\n  // User Profile System\n  // ============================================\n\n  // Analyze user prompts every N prompts to build/update your user profile\n  // When N uncaptured prompts accumulate, AI will analyze them to identify:\n  // - User preferences (code style, communication style, tool preferences)\n  // - User patterns (recurring topics, problem domains, technical interests)\n  // - User workflows (development habits, sequences, learning style)\n  // - Skill level (overall and per-domain assessment)\n  \"userProfileAnalysisInterval\": 10,\n\n  // Days before inactive items (all types) are eligible for removal\n  \"userProfileStaleDays\": 2,\n\n  // Number of preferences shown in UI\n  \"userProfileDisplayPreferences\": 20,\n  \n  // Number of patterns shown in UI\n  \"userProfileDisplayPatterns\": 15,\n  \n  // Number of workflows shown in UI\n  \"userProfileDisplayWorkflows\": 10,\n  \n  // Number of preferences injected into LLM conversation context\n  // Keep this small \u2014 the strongest signals are enough; more dilute LLM attention\n  \"userProfileInjectPreferences\": 5,\n  \n  // Number of patterns injected into LLM conversation context\n  \"userProfileInjectPatterns\": 5,\n  \n  // Number of workflows injected into LLM conversation context\n  \"userProfileInjectWorkflows\": 3,\n  \n  // Days before preference confidence starts to decay (if not reinforced)\n  // Preferences that aren't seen again will gradually lose confidence and be removed\n  \"userProfileConfidenceDecayDays\": 30,\n  \n  // Number of profile versions to keep in changelog (for rollback/debugging)\n  // Older versions are automatically cleaned up\n  \"userProfileChangelogRetentionCount\": 5,\n\n  // Minimum evidence count for a preference/pattern to survive confidence decay\n  // Items confirmed fewer times are more likely to be pruned when confidence decays\n  \"userProfileMinEvidenceForRetention\": 3,\n\n  // Periodically merge duplicate or irrelevant profile items with the configured AI provider\n  \"userProfileAutoCleanupEnabled\": true,\n  // Number of analyzed user prompts between automatic AI cleanup runs\n  \"userProfileAutoCleanupInterval\": 100,\n\n  // Enable LLM validation of existing preferences against recent behavior.\n  // When enabled, each analysis round checks if top-5 preferences still match recent prompts.\n  // Experimental \u2014 disabled by default.\n  \"userProfileValidationEnabled\": false,\n\n  // ============================================\n  // Search Settings\n  // ============================================\n  \n  // Minimum similarity score (0-1) for memory search results\n  \"similarityThreshold\": 0.6,\n\n  // Maximum number of memories to return in search results\n  \"maxMemories\": 10,\n\n  // ============================================\n  // Advanced Settings\n  // ============================================\n  \n  // Inject user profile into AI context (preferences, patterns, workflows)\n  \"injectProfile\": true\n}\n";
 export declare function normalizeAutoCaptureMaxContextBytes(value: number): number;
 export declare function normalizeAutoCleanupRetentionDays(value: number): number;
 declare function buildConfig(fileConfig: OmmsConfig): {
@@ -116,7 +121,7 @@ declare function buildConfig(fileConfig: OmmsConfig): {
     autoCaptureMaxRetries: number;
     autoCaptureMaxContextBytes: number;
     autoCaptureLanguage: string | undefined;
-    memoryProvider: "openai-chat" | "openai-responses" | "anthropic" | "minimax" | "orcarouter";
+    memoryProvider: "openai-chat" | "openai-responses" | "anthropic" | "minimax" | "orcarouter" | "google-gemini";
     memoryModel: string | undefined;
     memoryApiUrl: string | undefined;
     memoryApiKey: string | undefined;
@@ -134,6 +139,7 @@ declare function buildConfig(fileConfig: OmmsConfig): {
     autoBackfill: boolean;
     opencodeBackfillModel: string;
     piBackfillModel: string;
+    importPathMaps: import("./importer/importer.js").ImportPathMap[];
     webServerAutoStart: boolean;
     webServerEnabled: boolean;
     webServerPort: number;
@@ -208,7 +214,7 @@ export declare let CONFIG: {
     autoCaptureMaxRetries: number;
     autoCaptureMaxContextBytes: number;
     autoCaptureLanguage: string | undefined;
-    memoryProvider: "openai-chat" | "openai-responses" | "anthropic" | "minimax" | "orcarouter";
+    memoryProvider: "openai-chat" | "openai-responses" | "anthropic" | "minimax" | "orcarouter" | "google-gemini";
     memoryModel: string | undefined;
     memoryApiUrl: string | undefined;
     memoryApiKey: string | undefined;
@@ -226,6 +232,7 @@ export declare let CONFIG: {
     autoBackfill: boolean;
     opencodeBackfillModel: string;
     piBackfillModel: string;
+    importPathMaps: import("./importer/importer.js").ImportPathMap[];
     webServerAutoStart: boolean;
     webServerEnabled: boolean;
     webServerPort: number;

package/dist/config.js

@@ -7,6 +7,7 @@ import { resolveSecretValue } from "./services/secret-resolver.js";
 import { isPlaceholderApiKey } from "./services/ai/api-key-placeholder.js";
 import { getAutoCaptureProviderStatus } from "./services/ai/live-model-choice.js";
 import { parseBackfillModel } from "./importer/backfill-model.js";
+import { parseImportPathMaps } from "./importer/import-path-maps.js";
 import { resolveDefaultStoragePath, runLegacyStoreMigration, legacyMigrationPaths, } from "./services/legacy-migration.js";
 const OMMS_CONFIG_DIR = join(homedir(), ".config", "omms");
 const DATA_DIR = join(homedir(), ".omms");
@@ -55,6 +56,7 @@ const DEFAULTS = {
     autoBackfill: true,
     opencodeBackfillModel: "inherit",
     piBackfillModel: "inherit",
+    importPathMaps: [],
     webServerAutoStart: true,
     webServerEnabled: true,
     webServerPort: 4747,
@@ -198,8 +200,10 @@ export const CONFIG_TEMPLATE = `{
   
   // Start a background import of past chats on each host's next start.
   "autoBackfill": true,
-  // "piBackfillModel": "inherit", // or "provider/model"
-  // "opencodeBackfillModel": "inherit", // or "provider/model"
+  // "piBackfillModel": "inherit", // or "external", or "provider/model"
+  // "opencodeBackfillModel": "inherit", // or "external", or "provider/model"
+  // Directory maps for history recorded in moved or deleted directories.
+  // "importPathMaps": [{ "from": "~/code/app-feat-x", "to": "~/code/app" }],
 
   // Register the web app to start when you log in.
   "webServerAutoStart": true,
@@ -216,7 +220,7 @@ export const CONFIG_TEMPLATE = `{
   // "webServerAuthPassword": "",
   // "webServerAuthUsername": "",
 
-  // Required when webServerHost is not loopback. Protects /api/* with Bearer / X-Opencode-Mem-Token.
+  // Required when webServerHost is not loopback. Protects /api/* with Bearer / X-Omms-Token (legacy X-Opencode-Mem-Token still works).
   // "webServerApiToken": "env://OMMS_WEB_TOKEN",
   
   // ============================================
@@ -255,7 +259,8 @@ export const CONFIG_TEMPLATE = `{
    // Which model summarises your work, in this order:
    //   1. The host model below: opencodeProvider/opencodeModel in OpenCode,
    //      piProvider/piModel in Pi. Set the model to "inherit" to follow
-   //      whatever model the session is using.
+   //      whatever model the session is using, or to "external" to send
+   //      every call to the external API below.
    //   2. If no host model is set: the external API (memoryModel/memoryApiUrl/
    //      memoryApiKey further down).
    //   3. If neither is set: the session's own model.
@@ -285,7 +290,7 @@ export const CONFIG_TEMPLATE = `{
   
   "autoCaptureEnabled": true,
   
-  // Provider type: "openai-chat" | "openai-responses" | "anthropic" | "minimax" | "orcarouter"
+  // Provider type: "openai-chat" | "openai-responses" | "anthropic" | "minimax" | "orcarouter" | "google-gemini"
   // Note: "openai-chat" is a generic OpenAI API-compatible mode.
   // Any service that follows the OpenAI Chat Completions API can use it via custom "memoryApiUrl".
   "memoryProvider": "openai-chat",
@@ -554,14 +559,29 @@ export function normalizeAutoCleanupRetentionDays(value) {
     }
     return value;
 }
+/**
+ * The external API key, or undefined when its `env://` or `file://` source does
+ * not resolve in this process (a login web app does not see shell-profile
+ * variables). Readiness then reports the key as missing instead of the whole
+ * config failing to load.
+ */
+function resolveMemoryApiKey(value) {
+    try {
+        return resolveSecretValue(value);
+    }
+    catch {
+        return undefined;
+    }
+}
 function buildConfig(fileConfig) {
-    const memoryApiKey = resolveSecretValue(fileConfig.memoryApiKey);
+    const memoryApiKey = resolveMemoryApiKey(fileConfig.memoryApiKey);
     const embeddingDimensions = fileConfig.embeddingDimensions ??
         getEmbeddingDimensions(fileConfig.embeddingModel ?? DEFAULTS.embeddingModel);
     const autoCaptureMaxContextBytes = normalizeAutoCaptureMaxContextBytes(fileConfig.autoCaptureMaxContextBytes ?? DEFAULTS.autoCaptureMaxContextBytes);
     const userProfileAutoCleanupInterval = fileConfig.userProfileAutoCleanupInterval ?? DEFAULTS.userProfileAutoCleanupInterval;
     parseBackfillModel(fileConfig, "pi");
     parseBackfillModel(fileConfig, "opencode");
+    const importPathMaps = parseImportPathMaps(fileConfig.importPathMaps);
     for (const key of ["autoBackfill", "webServerAutoStart"]) {
         if (fileConfig[key] !== undefined && typeof fileConfig[key] !== "boolean") {
             throw new Error(`Invalid ${key} config`);
@@ -612,6 +632,7 @@ function buildConfig(fileConfig) {
         autoCaptureProviderStatus: getAutoCaptureProviderStatus({
             opencodeProvider: fileConfig.opencodeProvider,
             opencodeModel: fileConfig.opencodeModel,
+            memoryProvider: fileConfig.memoryProvider,
             memoryModel: fileConfig.memoryModel,
             memoryApiUrl: fileConfig.memoryApiUrl,
             memoryApiKey,
@@ -623,6 +644,7 @@ function buildConfig(fileConfig) {
         autoBackfill: fileConfig.autoBackfill ?? DEFAULTS.autoBackfill,
         opencodeBackfillModel: fileConfig.opencodeBackfillModel ?? DEFAULTS.opencodeBackfillModel,
         piBackfillModel: fileConfig.piBackfillModel ?? DEFAULTS.piBackfillModel,
+        importPathMaps,
         webServerAutoStart: fileConfig.webServerAutoStart ?? DEFAULTS.webServerAutoStart,
         webServerEnabled: fileConfig.webServerEnabled ?? DEFAULTS.webServerEnabled,
         webServerPort: fileConfig.webServerPort ?? DEFAULTS.webServerPort,
@@ -777,6 +799,7 @@ export function initConfig(directory, options = {}) {
     delete projectOverrides.autoBackfill;
     delete projectOverrides.opencodeBackfillModel;
     delete projectOverrides.piBackfillModel;
+    delete projectOverrides.importPathMaps;
     delete projectOverrides.webServerAutoStart;
     delete projectOverrides.webServerEnabled;
     const merged = { ...globalConfig, ...projectOverrides };

package/dist/core/internal-prompt.d.ts

@@ -0,0 +1,6 @@
+/**
+ * True when a prompt is omms's own structured-summary or profile-analysis
+ * request. Both hosts echo it back like a user message; recording or learning
+ * from it would create self-referential memories and a learning loop.
+ */
+export declare function isStructuredSummaryPromptMessage(userMessage: string): boolean;

package/dist/core/internal-prompt.js

@@ -0,0 +1,11 @@
+/**
+ * True when a prompt is omms's own structured-summary or profile-analysis
+ * request. Both hosts echo it back like a user message; recording or learning
+ * from it would create self-referential memories and a learning loop.
+ */
+export function isStructuredSummaryPromptMessage(userMessage) {
+    if (userMessage.includes("# User Profile Analysis")) {
+        return true;
+    }
+    return userMessage.includes("Analyze this conversation.") && userMessage.includes('type="skip"');
+}

package/dist/core/profile-analysis.d.ts

@@ -1,8 +1,11 @@
+import { z } from "zod";
 import type { UserProfileData } from "../services/user-profile/types.js";
 export interface ModelPort {
     provider: string;
     modelId: string;
     complete(systemPrompt: string, userPrompt: string): Promise<string>;
+    /** Host-enforced JSON output; callers fall back to `complete` and parse when absent. */
+    completeStructured?<T>(systemPrompt: string, userPrompt: string, schema: z.ZodType<T>): Promise<T>;
 }
 export interface ExistingProfileInput {
     id: string;

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

@@ -1,5 +1,6 @@
 import type { BackfillHost } from "./backfill-model.js";
 import { runHistoryImport, type HistoryImportModels } from "./run-import.js";
+import { type ImportSurface } from "./import-runs.js";
 type Run = typeof runHistoryImport;
 export interface AutoBackfillOptions {
     host: BackfillHost;
@@ -14,6 +15,10 @@ export interface AutoBackfillOptions {
     now?: () => number;
     enabled?: () => boolean;
     signal?: AbortSignal;
+    /** `web` for Run now and Resume on the Settings page. */
+    surface?: ImportSurface;
+    /** Skip the start-up delay and the autoBackfill switch: the user asked for this run. */
+    userStarted?: boolean;
 }
 /** Schedule one host's history import after startup; callers do not await it. */
 export declare function scheduleAutoBackfill(options: AutoBackfillOptions): Promise<void>;

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,53 @@
+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;
+export interface SettingsModel {
+    provider: string;
+    model: string;
+    name: string;
+}
+/** OpenCode's model access for web imports, Health, and Settings, when OpenCode runs this process. */
+export interface OpencodeHostModels {
+    isProviderConnected(providerID: string): boolean;
+    createImportModels(ref: {
+        providerID: string;
+        modelID: string;
+    }, directory: string): Promise<Required<HistoryImportModels>>;
+    listSettingsModels(): Promise<SettingsModel[] | null>;
+}
+export declare function registerOpencodeHostModels(models: OpencodeHostModels | null): void;
+export declare function getOpencodeHostModels(): OpencodeHostModels | null;
+/** 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,126 @@
+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);
+}
+let opencodeHostModels = null;
+export function registerOpencodeHostModels(models) {
+    opencodeHostModels = models;
+}
+export function getOpencodeHostModels() {
+    return opencodeHostModels;
+}
+/** 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>;