qlogicagent 2.6.1 → 2.9.0

package/dist/types/runtime/pet/pet-soul-service.d.ts

@@ -0,0 +1,71 @@
+/**
+ * PetSoulService — manages pet identity (hatching, persistence, stats).
+ *
+ * Hatching: deterministic identity via hash(userId) + LLM-generated soul.
+ * Persistence: stored in project workspace under .qlogicagent/pet/soul.json
+ */
+export interface PetStats {
+    grip: number;
+    patience: number;
+    curiosity: number;
+    appetite: number;
+    humor: number;
+}
+export interface PetSoul {
+    name: string;
+    species: string;
+    personality: string;
+    catchphrase: string;
+    stats: PetStats;
+    rarity: string;
+    breed?: string;
+    breedColors?: {
+        primary: string;
+        secondary: string;
+    };
+    level: number;
+    experience: number;
+    hatchedAt: string;
+}
+/** Breed system (design §6.2): 7 breeds with deterministic hash selection. */
+export interface PetBreed {
+    name: string;
+    colors: {
+        primary: string;
+        secondary: string;
+    };
+    rarity: string;
+}
+export declare class PetSoulService {
+    private workspaceDir;
+    private soul;
+    private storagePath;
+    constructor(workspaceDir: string);
+    /**
+     * Load existing soul from disk. Returns null if not hatched.
+     */
+    load(): PetSoul | null;
+    /**
+     * Hatch a new pet soul. Uses LLM for name/personality/catchphrase.
+     * If generateSoul is provided, uses it; otherwise falls back to defaults.
+     */
+    hatch(userId: string, generateSoul?: (rarity: string, stats: PetStats) => Promise<{
+        name: string;
+        personality: string;
+        catchphrase: string;
+    }>): Promise<PetSoul>;
+    /**
+     * Add experience points. Returns true if leveled up.
+     */
+    addExperience(xp: number): {
+        leveledUp: boolean;
+        level: number;
+        experience: number;
+    };
+    getSoul(): PetSoul | null;
+    /**
+     * Update soul (e.g., after growth/stat changes) and persist.
+     */
+    updateSoul(soul: PetSoul): void;
+    private persist;
+}

package/dist/types/runtime/prompt/environment-context.d.ts

@@ -35,3 +35,13 @@ export declare function createTaskGuidanceSection(domain?: TaskDomain): SystemPr
  * Tells the LLM when to use specialized tools vs. primitives.
  */
 export declare function createToolGuidanceSection(): SystemPromptSection;
+/**
+ * Create a system prompt section that instructs the model on response language.
+ * CC parity: only injected when language is explicitly set; when absent,
+ * the model follows the user's message language naturally.
+ *
+ * Key rule: always respond in the SAME language as the user's current message.
+ * This prevents confusion when system prompt contains mixed-language content
+ * (e.g., Chinese INDEX.md + English tool guidance).
+ */
+export declare function createLanguageSection(language?: string): SystemPromptSection;

package/dist/types/runtime/prompt/index.d.ts

@@ -1,4 +1,4 @@
 export { assembleSystemPrompt, clearSystemPromptSections, systemPromptSection, type SystemPromptSection, } from "./system-prompt-sections.js";
 export { getInstructions, buildInstructionsPrompt, resetInstructionCache, } from "./instruction-loader.js";
-export { createEnvironmentContextSection, createTaskGuidanceSection, createToolGuidanceSection } from "./environment-context.js";
+export { createEnvironmentContextSection, createTaskGuidanceSection, createToolGuidanceSection, createLanguageSection } from "./environment-context.js";
 export { detectTaskDomain, resolveTaskDomain, loadProjectTaskDomain, persistTaskDomain, shouldPersistDomain, type TaskDomain, type DomainResolutionContext } from "./task-domain.js";

package/dist/types/runtime/session/group-session-split.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Group Session Auto-Split — detects idle group sessions and creates successor sessions.
+ *
+ * When a group chat message arrives and the last session activity was > N hours ago,
+ * the old session is sealed and a new session is created with:
+ *   - previousSessionId linking to the predecessor
+ *   - carryoverSummary (from predecessor's taskSummary or last messages)
+ *   - Same groupKey, groupName, groupPlatform, projectId
+ *
+ * This prevents unbounded context growth in long-lived group chats.
+ */
+import { type SessionMetadata } from "./session-persistence.js";
+export interface GroupSplitResult {
+    /** Whether a split occurred */
+    split: boolean;
+    /** The session ID to use for the current turn (new or existing) */
+    activeSessionId: string;
+    /** If split, the sealed predecessor session ID */
+    sealedSessionId?: string;
+}
+/**
+ * Check whether a group session should be auto-split due to idle timeout.
+ * If yes, seal the old session and create a new successor.
+ *
+ * @param currentSession - The existing group session metadata
+ * @param projectRoot - The project workspace directory
+ * @returns Split result with the session ID to use
+ */
+export declare function maybeAutoSplitGroupSession(currentSession: SessionMetadata, projectRoot: string): Promise<GroupSplitResult>;
+/**
+ * Check whether a group session has exceeded MAX_TURNS hard limit.
+ * Called AFTER turn.end — soft-splits without interrupting the current turn.
+ *
+ * @param currentSession - The session that just finished a turn
+ * @param projectRoot - The project workspace directory
+ * @returns Split result (new session ready for next message, or no-op)
+ */
+export declare function maybeHardLimitSplit(currentSession: SessionMetadata, projectRoot: string): Promise<GroupSplitResult>;

package/dist/types/runtime/session/index.d.ts

@@ -1,2 +1,4 @@
-export { SessionState, type SessionUsageSnapshot, type SessionCostSnapshot } from "./session-state.js";
-export { appendMessage, saveSessionState, updateSessionMetadata, loadSessionForResume, listSessions, deleteSession, pruneOldSessions, shouldGenerateTaskSummary, maybeGenerateTaskSummary, type SessionMetadata, type PersistedSession, type SessionListEntry, type TaskSummaryDeps, } from "./session-persistence.js";
+export { SessionState, type SessionUsageSnapshot } from "./session-state.js";
+export { SessionLocator } from "./session-locator.js";
+export { appendMessage, saveSessionState, updateSessionMetadata, getSessionMetadata, loadSessionForResume, listSessions, deleteSession, pruneOldSessions, shouldGenerateTaskSummary, maybeGenerateTaskSummary, type SessionMetadata, type PersistedSession, type SessionListEntry, type TaskSummaryDeps, } from "./session-persistence.js";
+export { maybeAutoSplitGroupSession, type GroupSplitResult } from "./group-session-split.js";

package/dist/types/runtime/session/session-locator.d.ts

@@ -0,0 +1,24 @@
+/**
+ * SessionLocator — resolves session storage paths from projectId.
+ *
+ * Every session operation uses this locator to determine the correct
+ * filesystem path based on the session's owning projectId.
+ * When projectId is missing, falls back to scanning all projects.
+ */
+export declare class SessionLocator {
+    /** Get sessions root directory for a given projectId. */
+    getSessionsRoot(projectId: string): string;
+    /** Get the workspace dir for a project. */
+    getProjectWorkspaceDir(projectId: string): string;
+    /** Get the session directory path for a given projectId + sessionId. */
+    getSessionDir(projectId: string, sessionId: string): string;
+    /**
+     * Resolve the workspaceDir for a session given its projectId.
+     * If projectId is not provided, scans all projects for the session directory.
+     */
+    resolveWorkspaceDir(sessionId: string, projectId?: string): string;
+    /** Get the active project's workspace dir (for new session creation when no projectId specified). */
+    getActiveProjectWorkspaceDir(): string;
+    /** Get the active project's ID. */
+    getActiveProjectId(): string;
+}

package/dist/types/runtime/session/session-memory.d.ts

@@ -1,9 +1,9 @@
 /**
- * SessionMemory 鈥?In-memory session message store with JSONL persistence.
+ * SessionMemoryIn-memory session message store with JSONL persistence.
  *
  * CC alignment: messages live in memory during the session lifetime.
  * JSONL is the sole persistent source of truth (for crash recovery).
- * Gateway never owns message data 鈥?Agent is the single authority.
+ * Gateway never owns message dataAgent is the single authority.
  *
  * Design:
  *   - Map<sessionId, ChatMessage[]> holds active session messages
@@ -15,7 +15,7 @@ import type { ChatMessage } from "../../protocol/wire/index.js";
 export declare class SessionMemory {
     private sessions;
     private projectRoot;
-    constructor(projectRoot?: string);
+    constructor(projectRoot: string);
     setProjectRoot(projectRoot: string): void;
     /**
      * Get messages for a session. Lazy-loads from JSONL on first access.
@@ -35,7 +35,7 @@ export declare class SessionMemory {
     initSession(sessionId: string): void;
     /**
      * Drop a session from memory (e.g., on session.ended).
-     * Does NOT delete JSONL 鈥?data persists for future resume.
+     * Does NOT delete JSONLdata persists for future resume.
      */
     evictSession(sessionId: string): void;
     /**

package/dist/types/runtime/session/session-persistence.d.ts

@@ -1,113 +1,113 @@
 /**
- * Session Persistence 鈥?CC sessionRestore.ts + conversationRecovery.ts parity.
+ * Session Persistence — CC sessionRestore.ts + conversationRecovery.ts parity.
  *
  * Enables conversation resume by persisting:
  *   1. Message transcript (JSONL-based, append-only)
- *   2. Cost snapshot (atomic JSON)
- *   3. Session metadata (model, cwd, agent mode)
+ *   2. Session metadata (flat JSON, atomic write)
  *
- * Storage layout:
- *   <project>/.qlogicagent/sessions/<session-id>/   (when projectRoot provided)
- *   ~/.qlogicagent/sessions/<session-id>/            (fallback)
- *     transcript.jsonl   鈥?append-only message log
- *     state.json          鈥?cost snapshot + metadata
+ * Storage layout (ALL data lives under project workspace, NEVER global):
+ *   <project>/.qlogicagent/sessions/<session-id>/
+ *     transcript.jsonl   — append-only message log
+ *     metadata.json      — flat session metadata + usage stats
  *
  * Resume flow (CC processResumedConversation parity):
- *   1. loadSessionForResume(sessionId) 鈫?messages + cost
- *   2. Restore cost state into SessionState
+ *   1. loadSessionForResume(sessionId) → messages + metadata
+ *   2. Restore usage state into SessionState
  *   3. Feed messages as initial context to agent
- *
- * Reference: claude-code src/utils/sessionRestore.ts
- *            claude-code src/utils/conversationRecovery.ts
  */
 import type { ChatMessage } from "../../protocol/wire/index.js";
-import type { SessionCostSnapshot } from "./session-state.js";
+import type { SessionUsageSnapshot } from "./session-state.js";
 export interface SessionMetadata {
     sessionId: string;
-    createdAt: number;
-    lastActiveAt: number;
+    projectId: string;
+    createdAt: string;
+    lastActiveAt: string;
     model?: string;
     cwd?: string;
     turnCount: number;
     messageCount: number;
-    /** Title / description (auto-generated or user-set) */
     title?: string;
-    /** Task summary generated by LLM (CC maybeGenerateTaskSummary parity) */
     taskSummary?: string;
-    /** Timestamp of last task summary generation */
     taskSummaryGeneratedAt?: number;
-    /** ISO timestamp 鈥?session pinned in UI */
     pinnedAt?: string;
-    /** ISO timestamp 鈥?session archived (soft-deleted) */
     archivedAt?: string;
-    /** Project ID this session belongs to */
-    projectId?: string;
-    /** Session type: personal or group */
+    sealedAt?: string;
+    previousSessionId?: string;
+    carryoverSummary?: string;
     type?: "personal" | "group";
-    /** Owner user ID */
     ownerId?: string;
-    /** Group key for group sessions */
     groupKey?: string;
-    /** Group display name */
     groupName?: string;
-    /** Group platform (wechat, dingtalk, etc.) */
     groupPlatform?: string;
+    totalInputTokens?: number;
+    totalOutputTokens?: number;
 }
 export interface PersistedSession {
     metadata: SessionMetadata;
     messages: ChatMessage[];
-    costSnapshot?: SessionCostSnapshot;
 }
 export interface SessionListEntry {
     sessionId: string;
     title?: string;
-    lastActiveAt: number;
+    lastActiveAt: string;
     messageCount: number;
     model?: string;
     pinnedAt?: string;
     archivedAt?: string;
-    projectId?: string;
+    sealedAt?: string;
+    projectId: string;
     type?: "personal" | "group";
-    createdAt?: number;
+    createdAt: string;
+    groupKey?: string;
+    previousSessionId?: string;
+    carryoverSummary?: string | null;
 }
+/**
+ * Load session metadata only (lightweight — no transcript loading).
+ * Returns null if session doesn't exist or metadata is unreadable.
+ */
+export declare function getSessionMetadata(sessionId: string, projectRoot: string): SessionMetadata | null;
 /**
  * Append a message to the session transcript.
  * Creates the session directory if it doesn't exist.
  * When turnId is provided, it acts as a per-turn boundary marker enabling
  * reconciliation with Gateway's token_usage records.
+ *
+ * Robustness: catches disk-full and I/O errors without crashing the agent.
+ * Returns false if the write fails.
  */
-export declare function appendMessage(sessionId: string, message: ChatMessage, projectRoot?: string, turnId?: string): Promise<void>;
+export declare function appendMessage(sessionId: string, message: ChatMessage, projectRoot: string, turnId?: string): Promise<boolean>;
 /**
- * Save session state (cost + metadata) atomically.
+ * Save session metadata + usage stats atomically (flat structure).
  */
-export declare function saveSessionState(sessionId: string, costSnapshot: SessionCostSnapshot, metadata: Partial<SessionMetadata>, projectRoot?: string): Promise<void>;
+export declare function saveSessionState(sessionId: string, usageSnapshot: SessionUsageSnapshot, metadata: Partial<SessionMetadata>, projectRoot: string): Promise<void>;
 /**
  * Update specific metadata fields of a session without touching cost data.
  * Used by session CRUD RPC (rename, pin, archive, move-to-project).
  */
-export declare function updateSessionMetadata(sessionId: string, patch: Partial<SessionMetadata>, projectRoot?: string): Promise<SessionMetadata | null>;
+export declare function updateSessionMetadata(sessionId: string, patch: Partial<Record<keyof SessionMetadata, SessionMetadata[keyof SessionMetadata] | null>>, projectRoot: string): Promise<SessionMetadata | null>;
 /**
- * Load a persisted session for resume 鈥?CC loadConversationForResume parity.
+ * Load a persisted session for resume — CC loadConversationForResume parity.
  *
  * Returns null if the session doesn't exist or is corrupted.
  */
-export declare function loadSessionForResume(sessionId: string, projectRoot?: string): Promise<PersistedSession | null>;
+export declare function loadSessionForResume(sessionId: string, projectRoot: string): Promise<PersistedSession | null>;
 /**
- * List available sessions for resume 鈥?CC ResumeConversation picker.
+ * List available sessions for resume CC ResumeConversation picker.
  * Returns most-recent-first, up to `limit` entries.
  */
-export declare function listSessions(limit?: number, projectRoot?: string): Promise<SessionListEntry[]>;
+export declare function listSessions(limit: number | undefined, projectRoot: string): Promise<SessionListEntry[]>;
 /**
  * Delete a session (cleanup).
  */
-export declare function deleteSession(sessionId: string, projectRoot?: string): Promise<void>;
+export declare function deleteSession(sessionId: string, projectRoot: string): Promise<void>;
 /**
  * Prune old sessions beyond MAX_SESSIONS limit.
  * Deletes oldest sessions first.
  */
-export declare function pruneOldSessions(projectRoot?: string): Promise<number>;
+export declare function pruneOldSessions(projectRoot: string): Promise<number>;
 export interface TaskSummaryDeps {
-    transport: import("../../llm/transport.js").LLMTransport;
+    transport: import("@qlogic/provider-core").LLMTransport;
     apiKey: string;
     model: string;
 }
@@ -117,7 +117,8 @@ export interface TaskSummaryDeps {
  */
 export declare function shouldGenerateTaskSummary(metadata: SessionMetadata): boolean;
 /**
- * Generate and persist a task summary for a long session.
- * Fire-and-forget 鈥?errors are swallowed.
+ * Generate a concise session title from the user's first message.
+ * Lightweight LLM call — one-shot, no tool loop.
  */
-export declare function maybeGenerateTaskSummary(sessionId: string, metadata: SessionMetadata, recentMessages: ChatMessage[], deps: TaskSummaryDeps, projectRoot?: string): Promise<string | null>;
+export declare function generateSessionTitle(userMessage: string, deps: TaskSummaryDeps): Promise<string | null>;
+export declare function maybeGenerateTaskSummary(sessionId: string, metadata: SessionMetadata, recentMessages: ChatMessage[], deps: TaskSummaryDeps, projectRoot: string): Promise<string | null>;

package/dist/types/runtime/session/session-state.d.ts

@@ -1,5 +1,5 @@
 /**
- * Session State 鈥?CC session state parity.
+ * Session State CC session state parity.
  *
  * Unified state container for a single agent session:
  *   - Token usage / cost accumulation across turns
@@ -14,7 +14,7 @@
  * Reference: claude-code src/bootstrap/state.ts, src/cost-tracker.ts
  */
 import type { WireTokenUsage as TokenUsage } from "../../protocol/wire/index.js";
-/** Per-model usage accumulation 鈥?CC modelUsage parity */
+/** Per-model usage accumulation CC modelUsage parity */
 export interface ModelUsage {
     inputTokens: number;
     outputTokens: number;
@@ -36,8 +36,6 @@ export interface SessionUsageSnapshot {
     turnCount: number;
     lastSavedAt: number;
 }
-/** @deprecated Use SessionUsageSnapshot. Kept for persistence compat. */
-export type SessionCostSnapshot = SessionUsageSnapshot;
 export declare class SessionState {
     readonly sessionId: string;
     private _trustAccepted;
@@ -59,7 +57,7 @@ export declare class SessionState {
     /** Get all model usages as a plain object */
     getAllModelUsage(): Record<string, ModelUsage>;
     /**
-     * Add usage from an API response 鈥?CC addToTotalSessionCost() parity.
+     * Add usage from an API response CC addToTotalSessionCost() parity.
      * Tracks token counts only; pricing is handled by Hub/Admin.
      *
      * @param usage - Token counts from the API response

package/dist/types/skills/index.d.ts

@@ -4,8 +4,10 @@ export { MEMORY_TOOL_NAME, MEMORY_TOOL_ACTIONS, MEMORY_TOOL_SCHEMA, MEMORY_TOOL_
 export type { MemoryToolAction, MemoryToolParams, MemoryToolResult, MemoryToolExecutorDeps, } from "./memory/memory-tool.js";
 export { Memdir, getMemdirPath, getIndexPath } from "./memory/memdir.js";
 export type { MemdirFileInfo, MemdirResult } from "./memory/memdir.js";
-export { createQMemoryAdapter } from "./memory/qmemory-adapter.js";
-export type { QMemoryAdapterConfig, QMemoryHealthStatus, ExtractedMemoryItem, DecayOptions, DecayResult } from "./memory/qmemory-adapter.js";
+export { createMemoryProvider, resolveMemoryConfigFromEnv } from "./memory/memory-provider-factory.js";
+export type { MemoryProviderFactoryConfig, MemoryProviderFactoryResult } from "./memory/memory-provider-factory.js";
+export { LocalMemoryProvider } from "./memory/local-memory-provider.js";
+export type { LocalMemoryProviderConfig, ExtractedMemoryItem } from "./memory/local-memory-provider.js";
 export { THINK_TOOL_NAME, THINK_TOOL_SCHEMA, createThinkTool } from "./think-tool.js";
 export type { ThinkToolParams } from "./think-tool.js";
 export { READ_TOOL_NAME, READ_TOOL_SCHEMA, createReadTool } from "./tools/read-tool.js";
@@ -95,6 +97,10 @@ export { scanSource, scanSkillDirectory, hasCriticalFindings, isScannable, } fro
 export type { SkillGuardDeps } from "./skill-system/skill-guard.js";
 export { installSkill, uninstallSkill, createEmptyLockfile, } from "./skill-system/skill-source.js";
 export type { TrustLevel, ScanVerdict, SkillSourceDescriptor, SkillFetchResult, SkillFetchDeps, SkillStorageDeps, SkillLockEntry, SkillLockfile, SkillInstallResult, } from "./skill-system/skill-source.js";
+export { loadLifecycleStore, saveLifecycleStore, ensureRecord, recordInvocation, recordView, recordPatch, removeRecord, pinSkill, unpinSkill, runCurator, executeCuratorCycle, archiveSkillOnDisk, unarchiveSkillOnDisk, getSkillsByState, getLifecycleRecord, } from "./skill-system/skill-lifecycle.js";
+export type { SkillLifecycleState, SkillLifecycleRecord, SkillLifecycleStore, CuratorResult, } from "./skill-system/skill-lifecycle.js";
+export { validateSkillContent, generateSkillContent, autoFixFrontmatter, } from "./skill-system/skill-validation.js";
+export type { FrontmatterValidationResult } from "./skill-system/skill-validation.js";
 export { McpStdioClient } from "./mcp/mcp-stdio-client.js";
 export { McpManager, parseMcpConfig } from "./mcp/mcp-manager.js";
 export type { McpServerEntry, McpManagerConfig } from "./mcp/mcp-manager.js";

package/dist/types/skills/memory/implicit-extraction.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Implicit Memory Extraction — CC extractMemories lightweight port.
+ *
+ * Architecture:
+ *   Layer 1: Zero-cost signal detection (regex) — decides if turn has extractable content
+ *   Layer 2: Lightweight LLM pass (async, non-blocking) — extracts structured facts
+ *
+ * This runs AFTER turn.end, so the user already has their response.
+ * Layer 2 only fires for ~10-20% of turns (those with detectable signals).
+ *
+ * Reference: claude-code src/services/extractMemories/extractMemories.ts
+ */
+import type { LocalMemoryProvider } from "./local-memory-provider.js";
+export interface ExtractedFact {
+    text: string;
+    category: "personal_fact" | "preference" | "event" | "lesson" | "pattern" | "decision";
+    importance: number;
+    eventDate?: string;
+}
+export interface ImplicitExtractionDeps {
+    /** Local memory provider for writing extracted facts. */
+    localProvider: LocalMemoryProvider;
+    /** User ID. */
+    userId: string;
+    /** Logger. */
+    log: {
+        debug(msg: string): void;
+        warn(msg: string): void;
+    };
+    /**
+     * LLM invocation function (uses background/cheap model).
+     * Returns structured JSON string or null if unavailable.
+     */
+    llmExtract?: (prompt: string) => Promise<string | null>;
+}
+export interface TurnPair {
+    userMessage: string;
+    assistantMessage: string;
+}
+/**
+ * Layer 1: Detect if a user message contains signals worth extracting.
+ * Zero LLM cost — pure regex scanning.
+ *
+ * @returns true if the message likely contains extractable personal facts/events
+ */
+export declare function hasExtractionSignal(userMessage: string): boolean;
+/**
+ * Layer 2: Use a lightweight LLM to extract structured facts from a turn pair.
+ * Only called when Layer 1 signals are detected.
+ */
+export declare function extractFactsViaLlm(turn: TurnPair, llmExtract: (prompt: string) => Promise<string | null>, today: string): Promise<ExtractedFact[]>;
+/**
+ * Run the full implicit extraction pipeline for a completed turn.
+ * This is async and non-blocking — call it after turn.end.
+ *
+ * @returns Number of facts extracted and stored
+ */
+export declare function runImplicitExtraction(turn: TurnPair, deps: ImplicitExtractionDeps): Promise<number>;

package/dist/types/skills/memory/local-embedding.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Local Embedding — Pluggable embedding interface for local memory.
+ *
+ * Provides a unified interface for text → vector embedding.
+ * Strategies:
+ *   1. "api" — calls an external embedding API (OpenAI-compatible)
+ *   2. "onnx" — @xenova/transformers for fully offline embedding
+ *   3. "none" — no embeddings, FTS-only search (zero-dep fallback)
+ */
+export interface EmbeddingProvider {
+    readonly dimensions: number;
+    readonly model: string;
+    embed(text: string): Promise<Float32Array>;
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+}
+export interface EmbeddingApiConfig {
+    /** OpenAI-compatible embedding API base URL */
+    baseUrl: string;
+    /** API key */
+    apiKey: string;
+    /** Model name (e.g. "text-embedding-3-small") */
+    model: string;
+    /** Expected dimensions (default: 1536 for text-embedding-3-small) */
+    dimensions?: number;
+    /** Request timeout in ms (default: 10000) */
+    timeoutMs?: number;
+    /**
+     * Provider-specific API format.
+     * - "openai": Standard /v1/embeddings with input:string[] → data[].embedding (default)
+     * - "minimax": /v1/embeddings with texts:string[] → vectors[]
+     * - "volcengine": /v1/embeddings/multimodal with input:[{type,text}] → data.embedding
+     */
+    format?: "openai" | "minimax" | "volcengine";
+}
+export declare class NullEmbeddingProvider implements EmbeddingProvider {
+    readonly dimensions = 0;
+    readonly model = "none";
+    embed(_text: string): Promise<Float32Array>;
+    embedBatch(_texts: string[]): Promise<Float32Array[]>;
+}
+/**
+ * Wraps a primary EmbeddingProvider with automatic fallback to a local provider.
+ * When the primary fails (timeout, network error, 5xx), transparently retries with local.
+ *
+ * IMPORTANT: primary and fallback MUST have the same dimensions.
+ * If they differ, vectors in the same index will be incomparable.
+ * Use this only when both produce the same dimensionality (e.g. hub TEI bge-m3 1024d
+ * + local ONNX bge-m3-small 1024d).
+ */
+export declare class FallbackEmbeddingProvider implements EmbeddingProvider {
+    readonly dimensions: number;
+    readonly model: string;
+    private primary;
+    private fallback;
+    private onFallback?;
+    constructor(opts: {
+        primary: EmbeddingProvider;
+        fallback: EmbeddingProvider;
+        onFallback?: (error: Error) => void;
+    });
+    embed(text: string): Promise<Float32Array>;
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+}
+export declare class ApiEmbeddingProvider implements EmbeddingProvider {
+    readonly dimensions: number;
+    readonly model: string;
+    private baseUrl;
+    private apiKey;
+    private timeoutMs;
+    private format;
+    constructor(config: EmbeddingApiConfig);
+    embed(text: string): Promise<Float32Array>;
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+    private buildRequest;
+    private parseResponse;
+}
+export interface LocalEmbeddingConfig {
+    strategy: "api" | "onnx" | "none";
+    api?: EmbeddingApiConfig;
+    onnx?: OnnxEmbeddingConfig;
+    /**
+     * When strategy=api, if the API fails (timeout/error), fallback to this.
+     * - "onnx": use local ONNX model (download on first use, ~23MB)
+     * - "none": give up embedding (FTS-only)
+     * Requires same dimensions for vector compatibility. Default ONNX model
+     * (bge-small-zh-v1.5, 512d) differs from bge-m3 (1024d).
+     * Accept dimension mismatch for degraded recall in fallback mode.
+     */
+    fallbackStrategy?: "onnx" | "none";
+    fallbackOnnx?: OnnxEmbeddingConfig;
+}
+export interface OnnxEmbeddingConfig {
+    /** Model ID for @xenova/transformers (default: "Xenova/bge-small-zh-v1.5") */
+    modelId?: string;
+    /** Expected dimensions (default: 512 for bge-small-zh-v1.5) */
+    dimensions?: number;
+    /** Max sequence length before truncation (default: 256) */
+    maxLength?: number;
+    /** Override local model path (for testing). */
+    localModelPath?: string;
+}
+/**
+ * Offline embedding provider using ONNX Runtime via @xenova/transformers.
+ *
+ * Model is lazily downloaded on first use (~24MB for bge-small-zh-v1.5 quantized).
+ * Subsequent loads are instant from local cache (~/.qlogicagent/models/).
+ *
+ * For China network: set ONNX_MODEL_MIRROR to OSS URL or HF_MIRROR=https://hf-mirror.com
+ */
+export declare class OnnxEmbeddingProvider implements EmbeddingProvider {
+    readonly dimensions: number;
+    readonly model: string;
+    private maxLength;
+    private localModelPath;
+    private pipeline;
+    private loading;
+    constructor(config?: OnnxEmbeddingConfig);
+    private getPipeline;
+    embed(text: string): Promise<Float32Array>;
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+    /**
+     * Pre-download and load the ONNX model without blocking.
+     * Call this at process startup for instant readiness on first real embed().
+     */
+    warmup(): Promise<void>;
+}
+export interface WarmupResult {
+    onnxAvailable: boolean;
+    modelCached: boolean;
+    modelDownloaded: boolean;
+    dimensions: number;
+    error?: string;
+}
+/**
+ * Run at process startup to verify environment and pre-download ONNX model.
+ *
+ * - Checks if @xenova/transformers is installed
+ * - Checks if model already in local cache
+ * - If not cached, downloads from OSS CDN in background
+ * - Returns status for diagnostics logging
+ *
+ * Fire-and-forget: never throws, never blocks critical path.
+ */
+export declare function warmupEmbeddingModel(config?: OnnxEmbeddingConfig): Promise<WarmupResult>;
+/**
+ * Create an embedding provider based on configuration.
+ *
+ * Resolution order:
+ *   1. Explicit config (api/onnx/none)
+ *   2. Auto-detect: @xenova/transformers available → use ONNX (lazy download)
+ *   3. Fallback to NullEmbeddingProvider (FTS-only)
+ *
+ * When config.fallbackStrategy is set and strategy=api, wraps primary in
+ * FallbackEmbeddingProvider for automatic local retry on API failure.
+ */
+export declare function createEmbeddingProvider(config?: LocalEmbeddingConfig): EmbeddingProvider;
+/**
+ * Known provider → format mapping.
+ * Used by auto-cascade to build the correct EmbeddingApiConfig
+ * when the user's LLM provider also has an embedding API.
+ */
+export declare const PROVIDER_EMBEDDING_REGISTRY: Record<string, {
+    format: "openai" | "minimax" | "volcengine";
+    baseUrl: string;
+    defaultModel: string;
+    defaultDimensions: number;
+}>;
+/**
+ * Resolve EmbeddingApiConfig from a known provider name + API key.
+ * Returns null if the provider has no known embedding endpoint.
+ */
+export declare function resolveProviderEmbeddingConfig(provider: string, apiKey: string, overrides?: {
+    model?: string;
+    baseUrl?: string;
+    dimensions?: number;
+}): EmbeddingApiConfig | null;