qlogicagent 2.6.0 → 2.7.0

package/dist/types/protocol/wire/notification-payloads.d.ts

@@ -66,8 +66,10 @@ export interface TurnEndNotification {
 /** Turn failed. */
 export interface TurnErrorNotification {
     turnId: string;
-    error: string;
-    code?: string;
+    error: {
+        message: string;
+        code?: string;
+    };
 }
 /** Agent self-recovered from an error. */
 export interface TurnRecoveryNotification {
@@ -256,6 +258,15 @@ export interface TurnSkillInstructionNotification {
     turnId: string;
     instruction: unknown;
 }
+/** Agent detected a repeating pattern that should be acquired as a skill from hub. */
+export interface TurnSkillAcquisitionNeededNotification {
+    turnId: string;
+    pattern: {
+        suggestedName: string;
+        description: string;
+        tools: string[];
+    };
+}
 /** Agent asks the user a clarifying question mid-turn. */
 export interface TurnAskUserNotification {
     askId?: string;
@@ -341,7 +352,7 @@ export interface AgentsErrorNotification {
 export interface SoloProgressNotification {
     soloId: string;
     agentId: string;
-    state: "pending" | "running" | "completed" | "failed";
+    state: "pending" | "running" | "completed" | "failed" | "idle";
     progress?: string;
 }
 /** Solo evaluation completed. */
@@ -434,6 +445,40 @@ export interface ProductTaskOutputDeltaNotification {
     taskId: string;
     text: string;
 }
+/** Leader agent produced a structured plan — client should present to user. */
+export interface ProductPlanReadyNotification {
+    productId: string;
+    plan: {
+        name: string;
+        modules: Array<{
+            name: string;
+            description: string;
+            suggestedAgentId?: string;
+        }>;
+        instances: Array<{
+            name: string;
+            agentId: string;
+            role: string;
+        }>;
+        tasks: Array<{
+            taskId: string;
+            assignee: string;
+            prompt: string;
+            dependsOn?: string[];
+        }>;
+        reasoning: string;
+    };
+}
+/** Planning failed. */
+export interface ProductPlanFailedNotification {
+    productId: string;
+    error: string;
+}
+/** Streaming text output from leader during planning. */
+export interface ProductPlanningDeltaNotification {
+    productId: string;
+    text: string;
+}
 /** Plan interrupted. */
 export interface PlanInterruptedNotification {
     planId: string;
@@ -543,6 +588,7 @@ export interface NotificationMethodMap {
     "turn.artifact": TurnArtifactNotification;
     "tool.approval.request": ToolApprovalRequestNotification;
     "turn.skill_instruction": TurnSkillInstructionNotification;
+    "turn.skill_acquisition_needed": TurnSkillAcquisitionNeededNotification;
     "turn.ask_user": TurnAskUserNotification;
     "memory.updated": MemoryUpdatedNotification;
     "memory.decay.completed": MemoryDecayCompletedNotification;
@@ -569,6 +615,9 @@ export interface NotificationMethodMap {
     "product.dagTopology": ProductDagTopologyNotification;
     "product.budgetUpdate": ProductBudgetUpdateNotification;
     "product.taskOutput": ProductTaskOutputDeltaNotification;
+    "product.planReady": ProductPlanReadyNotification;
+    "product.planFailed": ProductPlanFailedNotification;
+    "product.planningDelta": ProductPlanningDeltaNotification;
     "plan.interrupted": PlanInterruptedNotification;
     "project.created": ProjectCreatedNotification;
     "project.switched": ProjectSwitchedNotification;

package/dist/types/runtime/execution/dream-agent.d.ts

@@ -18,6 +18,8 @@ export interface DreamTriggerConfig {
     minHours: number;
     /** Minimum sessions since last consolidation. Default: 5. */
     minSessions: number;
+    /** Minimum turns in current session as alternative gate. Default: 20. */
+    minTurnsInSession: number;
     /** Scan throttle interval (ms). Default: 600_000 (10 min). */
     scanIntervalMs: number;
     /** Force run, ignoring gates. */
@@ -32,6 +34,8 @@ export interface DreamContext {
     currentSessionId: string;
     /** Callback to list session IDs touched since a timestamp. */
     listSessionsSince: (sinceMs: number) => Promise<string[]>;
+    /** Turn count in current session (for single-session users). */
+    currentSessionTurnCount?: number;
 }
 export interface DreamToolRestriction {
     toolName: string;
@@ -77,6 +81,8 @@ export declare function canUseDreamTool(memoryRoot: string, restriction: DreamTo
 export declare function buildConsolidationPrompt(memoryRoot: string, transcriptDir: string, sessionIds: string[], opts?: {
     hasQMemory?: boolean;
     categoryContext?: string;
+    temporalContext?: string;
+    profileContext?: string;
 }): string;
 /**
  * Check whether dream consolidation should run.
@@ -160,11 +166,11 @@ export interface DreamRunDeps {
     /** Parent abort signal */
     parentSignal?: AbortSignal;
     /**
-     * QMemory adapter — when provided, Dream Agent acts as the "hippocampus":
+     * Memory provider — when provided, Dream Agent acts as the "hippocampus":
      * reads existing long-term memories, writes classified session insights,
      * and submits feedback on outdated/contradicted memories.
      */
-    qmemoryAdapter?: {
+    memoryProvider?: {
         search(query: string, userId: string, options?: {
             limit?: number;
         }): Promise<Array<{
@@ -178,10 +184,31 @@ export interface DreamRunDeps {
         }): Promise<{
             memoriesAdded: number;
         }>;
-        feedback?(memoryIds: string[], signal: string, sessionId?: string): Promise<void>;
+        feedback?(memoryIds: string[], signal: "useful" | "irrelevant" | "outdated" | "wrong"): Promise<{
+            affected: number;
+        }>;
+        /** Recent activity summary for temporal context injection into Dream. */
+        getActivitySummary?(userId: string, days?: number): {
+            dailyCounts: Array<{
+                date: string;
+                count: number;
+            }>;
+            highlights: Array<{
+                text: string;
+                category: string;
+                importance: number;
+                date: string;
+            }>;
+        };
+        /** Synthesize a timeline narrative for a time range. */
+        synthesizeTimeline?(userId: string, startMs: number, endMs: number): string;
+        /** Get/set user profile entries. */
+        getProfile?(userId: string, key: string): string | null;
+        setProfile?(userId: string, key: string, value: string): void;
+        getAllProfiles?(userId: string): Record<string, string>;
     };
-    /** User ID for QMemory operations. */
-    qmemoryUserId?: string;
+    /** User ID for memory operations. */
+    memoryUserId?: string;
 }
 /**
  * Run a complete dream consolidation using an isolated forked agent.

package/dist/types/runtime/execution/memory-decay.d.ts

@@ -1,4 +1,14 @@
-import type { DecayOptions, DecayResult } from "../../skills/memory/qmemory-adapter.js";
+/** Options for triggering a decay cycle. */
+export interface DecayOptions {
+    temporalExpiry?: boolean;
+    stalenessDecay?: boolean;
+    noiseArchival?: boolean;
+}
+/** Result of a decay cycle. */
+export interface DecayResult {
+    decayed: number;
+    archived: number;
+}
 export interface DecayConfig {
     /** Minimum hours between decay cycles. Default: 24. */
     minIntervalHours: number;
@@ -20,11 +30,13 @@ export declare function shouldTriggerDecay(memoryRoot: string, config?: Partial<
  */
 export declare function markDecayComplete(memoryRoot: string): Promise<void>;
 export interface DecayCycleDeps {
-    /** QMemory adapter with triggerDecay method. */
+    /** Memory provider with triggerDecay method. */
     adapter: {
-        triggerDecay(userId: string, options?: DecayOptions): Promise<DecayResult>;
+        triggerDecay(userId: string, maxAgeDays?: number): Promise<{
+            decayed: number;
+        }>;
     };
-    /** User ID for QMemory operations. */
+    /** User ID for memory operations. */
     userId: string;
     /** Memory root directory (for gate marker). */
     memoryRoot: string;
@@ -51,7 +63,7 @@ export interface DecayCycleResult {
  *
  * Lifecycle:
  *   1. Check time gate (24h default)
- *   2. Call QMemory /v1/admin/decay
+ *   2. Call local memory provider decay
  *   3. Mark completion timestamp
  */
 export declare function runDecayCycle(deps: DecayCycleDeps): Promise<DecayCycleResult>;

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

@@ -1,5 +1,6 @@
 import type { HookRegistry } from "../../contracts/hooks.js";
 import type { MemoryProvider } from "../../protocol/wire/index.js";
+import type { LocalMemoryProvider } from "../../skills/memory/local-memory-provider.js";
 import type { Memdir } from "../../skills/memory/memdir.js";
 export declare const MEMORY_PREFETCH_CONFIG: {
     readonly MAX_SESSION_BYTES: number;
@@ -9,6 +10,8 @@ export declare const MEMORY_PREFETCH_CONFIG: {
 export interface MemoryHooksDeps {
     /** QMemory adapter (MemoryProvider with search/health). */
     memoryProvider?: MemoryProvider;
+    /** Local memory provider for direct writes (auto-extract). */
+    localMemoryProvider?: LocalMemoryProvider;
     /** User ID for memory lookups. */
     userId: string;
     /** Logger. */
@@ -16,6 +19,12 @@ export interface MemoryHooksDeps {
         debug(msg: string): void;
         warn(msg: string): void;
     };
+    /** Access to recent messages (for auto-extract). Set externally per turn. */
+    getLastUserMessage?: () => string | undefined;
+    /** Access to last assistant response (for implicit extraction). Set externally per turn. */
+    getLastAssistantMessage?: () => string | undefined;
+    /** Background LLM for implicit extraction. If provided, enables Layer 2. */
+    llmExtract?: (prompt: string) => Promise<string | null>;
 }
 /** Session-scoped state for dedup and byte budget (CC parity). */
 export interface MemoryPrefetchState {

package/dist/types/runtime/infra/acp-types.d.ts

@@ -158,6 +158,15 @@ export interface SoloStartParams {
     task: string;
     agents: string[];
     cwd: string;
+    /** Optional shared config injected into all agents (memory seed, rules, etc). */
+    sharedConfig?: {
+        /** Initial memory entries to seed into each agent's context. */
+        memory?: string[];
+        /** Rules/instructions to inject as system prompt prefix. */
+        rules?: string[];
+        /** Model override for all agents. */
+        model?: string;
+    };
 }
 /** solo.status / solo.cancel / solo.select RPC params. */
 export interface SoloIdParams {
@@ -168,6 +177,22 @@ export interface SoloSelectParams {
     soloId: string;
     winnerId: string;
 }
+/** solo.message RPC params — send follow-up to individual agent. */
+export interface SoloMessageParams {
+    soloId: string;
+    agentId: string;
+    content: string;
+    /** For duplicate agentIds, specify which instance (0-based index). */
+    agentIndex?: number;
+}
+/** solo.evaluate RPC params — user-triggered evaluation with chosen evaluator. */
+export interface SoloEvaluateParams {
+    soloId: string;
+    /** Which agent in the solo session should perform the evaluation comparison. */
+    evaluatorAgentId: string;
+    /** For duplicate agentIds, specify which instance (0-based index). */
+    evaluatorIndex?: number;
+}
 export type ProductInstanceState = "idle" | "running" | "completed" | "failed" | "paused";
 /** Product budget configuration & runtime counters. */
 export interface ProductBudget {
@@ -187,6 +212,69 @@ export interface ProductCreateParams {
         maxDuration?: number;
     };
 }
+/**
+ * product.plan RPC params — starts an interactive planning session.
+ * The leader agent decomposes the goal into modules and proposes a DAG.
+ */
+export interface ProductPlanParams {
+    /** High-level project goal (e.g. "build a multiplayer MMO game"). */
+    goal: string;
+    /** Working directory for the project. */
+    cwd: string;
+    /** Which agent acts as the team leader (must be ACP-compatible). */
+    leaderAgentId: string;
+    /** Optional: project name. Leader can suggest one if omitted. */
+    name?: string;
+    /** Optional: budget constraints communicated to leader during planning. */
+    budget?: {
+        maxTotalTokens?: number;
+        maxDuration?: number;
+    };
+}
+/** The structured plan produced by the leader agent. */
+export interface ProductPlan {
+    /** Product/project name. */
+    name: string;
+    /** Modules the project is decomposed into. */
+    modules: Array<{
+        name: string;
+        description: string;
+        /** Suggested agent for this module (leader's recommendation). */
+        suggestedAgentId?: string;
+    }>;
+    /** Proposed team members (leader may suggest agents for each module). */
+    instances: ProductInstanceDef[];
+    /** Proposed task DAG. */
+    tasks: ProductTaskDef[];
+    /** Leader's explanation of the decomposition strategy. */
+    reasoning: string;
+}
+/**
+ * product.confirm RPC params — user confirms (optionally modified) plan.
+ * This starts the actual DAG execution with the leader managing progress.
+ */
+export interface ProductConfirmParams {
+    /** The planning session product ID (returned by product.plan). */
+    productId: string;
+    /** Final instances (user may have reassigned agents). */
+    instances: ProductInstanceDef[];
+    /** Final task DAG (user may have modified). */
+    tasks: ProductTaskDef[];
+    /** Budget for execution phase. */
+    budget?: {
+        maxTotalTokens?: number;
+        maxDuration?: number;
+    };
+}
+/**
+ * product.message RPC params — user sends a message to the leader during any phase.
+ * Supports: multi-turn planning dialogue, and user intervention during execution.
+ */
+export interface ProductMessageParams {
+    productId: string;
+    /** User's message content. */
+    content: string;
+}
 /** product.resume / product.pause / product.checkpoint / product.status RPC params. */
 export interface ProductIdParams {
     productId: string;

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/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;