agiagent-dev 2026.1.30

package/dist/memory/embeddings.js

@@ -0,0 +1,175 @@
+import fsSync from "node:fs";
+import { resolveUserPath } from "../utils.js";
+import { createGeminiEmbeddingProvider } from "./embeddings-gemini.js";
+import { createOpenAiEmbeddingProvider } from "./embeddings-openai.js";
+import { importNodeLlamaCpp } from "./node-llama.js";
+const DEFAULT_LOCAL_MODEL = "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf";
+function canAutoSelectLocal(options) {
+    const modelPath = options.local?.modelPath?.trim();
+    if (!modelPath) {
+        return false;
+    }
+    if (/^(hf:|https?:)/i.test(modelPath)) {
+        return false;
+    }
+    const resolved = resolveUserPath(modelPath);
+    try {
+        return fsSync.statSync(resolved).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isMissingApiKeyError(err) {
+    const message = formatError(err);
+    return message.includes("No API key found for provider");
+}
+async function createLocalEmbeddingProvider(options) {
+    const modelPath = options.local?.modelPath?.trim() || DEFAULT_LOCAL_MODEL;
+    const modelCacheDir = options.local?.modelCacheDir?.trim();
+    // Lazy-load node-llama-cpp to keep startup light unless local is enabled.
+    const { getLlama, resolveModelFile, LlamaLogLevel } = await importNodeLlamaCpp();
+    let llama = null;
+    let embeddingModel = null;
+    let embeddingContext = null;
+    const ensureContext = async () => {
+        if (!llama) {
+            llama = await getLlama({ logLevel: LlamaLogLevel.error });
+        }
+        if (!embeddingModel) {
+            const resolved = await resolveModelFile(modelPath, modelCacheDir || undefined);
+            embeddingModel = await llama.loadModel({ modelPath: resolved });
+        }
+        if (!embeddingContext) {
+            embeddingContext = await embeddingModel.createEmbeddingContext();
+        }
+        return embeddingContext;
+    };
+    return {
+        id: "local",
+        model: modelPath,
+        embedQuery: async (text) => {
+            const ctx = await ensureContext();
+            const embedding = await ctx.getEmbeddingFor(text);
+            return Array.from(embedding.vector);
+        },
+        embedBatch: async (texts) => {
+            const ctx = await ensureContext();
+            const embeddings = await Promise.all(texts.map(async (text) => {
+                const embedding = await ctx.getEmbeddingFor(text);
+                return Array.from(embedding.vector);
+            }));
+            return embeddings;
+        },
+    };
+}
+export async function createEmbeddingProvider(options) {
+    const requestedProvider = options.provider;
+    const fallback = options.fallback;
+    const createProvider = async (id) => {
+        if (id === "local") {
+            const provider = await createLocalEmbeddingProvider(options);
+            return { provider };
+        }
+        if (id === "gemini") {
+            const { provider, client } = await createGeminiEmbeddingProvider(options);
+            return { provider, gemini: client };
+        }
+        const { provider, client } = await createOpenAiEmbeddingProvider(options);
+        return { provider, openAi: client };
+    };
+    const formatPrimaryError = (err, provider) => provider === "local" ? formatLocalSetupError(err) : formatError(err);
+    if (requestedProvider === "auto") {
+        const missingKeyErrors = [];
+        let localError = null;
+        if (canAutoSelectLocal(options)) {
+            try {
+                const local = await createProvider("local");
+                return { ...local, requestedProvider };
+            }
+            catch (err) {
+                localError = formatLocalSetupError(err);
+            }
+        }
+        for (const provider of ["openai", "gemini"]) {
+            try {
+                const result = await createProvider(provider);
+                return { ...result, requestedProvider };
+            }
+            catch (err) {
+                const message = formatPrimaryError(err, provider);
+                if (isMissingApiKeyError(err)) {
+                    missingKeyErrors.push(message);
+                    continue;
+                }
+                throw new Error(message, { cause: err });
+            }
+        }
+        const details = [...missingKeyErrors, localError].filter(Boolean);
+        if (details.length > 0) {
+            throw new Error(details.join("\n\n"));
+        }
+        throw new Error("No embeddings provider available.");
+    }
+    try {
+        const primary = await createProvider(requestedProvider);
+        return { ...primary, requestedProvider };
+    }
+    catch (primaryErr) {
+        const reason = formatPrimaryError(primaryErr, requestedProvider);
+        if (fallback && fallback !== "none" && fallback !== requestedProvider) {
+            try {
+                const fallbackResult = await createProvider(fallback);
+                return {
+                    ...fallbackResult,
+                    requestedProvider,
+                    fallbackFrom: requestedProvider,
+                    fallbackReason: reason,
+                };
+            }
+            catch (fallbackErr) {
+                // oxlint-disable-next-line preserve-caught-error
+                throw new Error(`${reason}\n\nFallback to ${fallback} failed: ${formatError(fallbackErr)}`, { cause: fallbackErr });
+            }
+        }
+        throw new Error(reason, { cause: primaryErr });
+    }
+}
+function formatError(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}
+function isNodeLlamaCppMissing(err) {
+    if (!(err instanceof Error)) {
+        return false;
+    }
+    const code = err.code;
+    if (code === "ERR_MODULE_NOT_FOUND") {
+        return err.message.includes("node-llama-cpp");
+    }
+    return false;
+}
+function formatLocalSetupError(err) {
+    const detail = formatError(err);
+    const missing = isNodeLlamaCppMissing(err);
+    return [
+        "Local embeddings unavailable.",
+        missing
+            ? "Reason: optional dependency node-llama-cpp is missing (or failed to install)."
+            : detail
+                ? `Reason: ${detail}`
+                : undefined,
+        missing && detail ? `Detail: ${detail}` : null,
+        "To enable local embeddings:",
+        "1) Use Node 22 LTS (recommended for installs/updates)",
+        missing
+            ? "2) Reinstall AGIAgent (this should install node-llama-cpp): npm i -g agiagent@latest"
+            : null,
+        "3) If you use pnpm: pnpm approve-builds (select node-llama-cpp), then pnpm rebuild node-llama-cpp",
+        'Or set agents.defaults.memorySearch.provider = "openai" (remote).',
+    ]
+        .filter(Boolean)
+        .join("\n");
+}

package/dist/memory/headers-fingerprint.d.ts

@@ -0,0 +1 @@
+export declare function fingerprintHeaderNames(headers: Record<string, string> | undefined): string[];

package/dist/memory/headers-fingerprint.js

@@ -0,0 +1,18 @@
+function normalizeHeaderName(name) {
+    return name.trim().toLowerCase();
+}
+export function fingerprintHeaderNames(headers) {
+    if (!headers) {
+        return [];
+    }
+    const out = [];
+    for (const key of Object.keys(headers)) {
+        const normalized = normalizeHeaderName(key);
+        if (!normalized) {
+            continue;
+        }
+        out.push(normalized);
+    }
+    out.sort((a, b) => a.localeCompare(b));
+    return out;
+}

package/dist/memory/hybrid.d.ts

@@ -0,0 +1,34 @@
+export type HybridSource = string;
+export type HybridVectorResult = {
+    id: string;
+    path: string;
+    startLine: number;
+    endLine: number;
+    source: HybridSource;
+    snippet: string;
+    vectorScore: number;
+};
+export type HybridKeywordResult = {
+    id: string;
+    path: string;
+    startLine: number;
+    endLine: number;
+    source: HybridSource;
+    snippet: string;
+    textScore: number;
+};
+export declare function buildFtsQuery(raw: string): string | null;
+export declare function bm25RankToScore(rank: number): number;
+export declare function mergeHybridResults(params: {
+    vector: HybridVectorResult[];
+    keyword: HybridKeywordResult[];
+    vectorWeight: number;
+    textWeight: number;
+}): Array<{
+    path: string;
+    startLine: number;
+    endLine: number;
+    score: number;
+    snippet: string;
+    source: HybridSource;
+}>;

package/dist/memory/hybrid.js

@@ -0,0 +1,63 @@
+export function buildFtsQuery(raw) {
+    const tokens = raw
+        .match(/[A-Za-z0-9_]+/g)
+        ?.map((t) => t.trim())
+        .filter(Boolean) ?? [];
+    if (tokens.length === 0) {
+        return null;
+    }
+    const quoted = tokens.map((t) => `"${t.replaceAll('"', "")}"`);
+    return quoted.join(" AND ");
+}
+export function bm25RankToScore(rank) {
+    const normalized = Number.isFinite(rank) ? Math.max(0, rank) : 999;
+    return 1 / (1 + normalized);
+}
+export function mergeHybridResults(params) {
+    const byId = new Map();
+    for (const r of params.vector) {
+        byId.set(r.id, {
+            id: r.id,
+            path: r.path,
+            startLine: r.startLine,
+            endLine: r.endLine,
+            source: r.source,
+            snippet: r.snippet,
+            vectorScore: r.vectorScore,
+            textScore: 0,
+        });
+    }
+    for (const r of params.keyword) {
+        const existing = byId.get(r.id);
+        if (existing) {
+            existing.textScore = r.textScore;
+            if (r.snippet && r.snippet.length > 0) {
+                existing.snippet = r.snippet;
+            }
+        }
+        else {
+            byId.set(r.id, {
+                id: r.id,
+                path: r.path,
+                startLine: r.startLine,
+                endLine: r.endLine,
+                source: r.source,
+                snippet: r.snippet,
+                vectorScore: 0,
+                textScore: r.textScore,
+            });
+        }
+    }
+    const merged = Array.from(byId.values()).map((entry) => {
+        const score = params.vectorWeight * entry.vectorScore + params.textWeight * entry.textScore;
+        return {
+            path: entry.path,
+            startLine: entry.startLine,
+            endLine: entry.endLine,
+            score,
+            snippet: entry.snippet,
+            source: entry.source,
+        };
+    });
+    return merged.toSorted((a, b) => b.score - a.score);
+}

package/dist/memory/index.d.ts

@@ -0,0 +1,2 @@
+export type { MemoryIndexManager, MemorySearchResult } from "./manager.js";
+export { getMemorySearchManager, type MemorySearchManagerResult } from "./search-manager.js";

package/dist/memory/index.js

@@ -0,0 +1 @@
+export { getMemorySearchManager } from "./search-manager.js";

package/dist/memory/internal.d.ts

@@ -0,0 +1,26 @@
+export type MemoryFileEntry = {
+    path: string;
+    absPath: string;
+    mtimeMs: number;
+    size: number;
+    hash: string;
+};
+export type MemoryChunk = {
+    startLine: number;
+    endLine: number;
+    text: string;
+    hash: string;
+};
+export declare function ensureDir(dir: string): string;
+export declare function normalizeRelPath(value: string): string;
+export declare function normalizeExtraMemoryPaths(workspaceDir: string, extraPaths?: string[]): string[];
+export declare function isMemoryPath(relPath: string): boolean;
+export declare function listMemoryFiles(workspaceDir: string, extraPaths?: string[]): Promise<string[]>;
+export declare function hashText(value: string): string;
+export declare function buildFileEntry(absPath: string, workspaceDir: string): Promise<MemoryFileEntry>;
+export declare function chunkMarkdown(content: string, chunking: {
+    tokens: number;
+    overlap: number;
+}): MemoryChunk[];
+export declare function parseEmbedding(raw: string): number[];
+export declare function cosineSimilarity(a: number[], b: number[]): number;

package/dist/memory/internal.js

@@ -0,0 +1,240 @@
+import crypto from "node:crypto";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+export function ensureDir(dir) {
+    try {
+        fsSync.mkdirSync(dir, { recursive: true });
+    }
+    catch { }
+    return dir;
+}
+export function normalizeRelPath(value) {
+    const trimmed = value.trim().replace(/^[./]+/, "");
+    return trimmed.replace(/\\/g, "/");
+}
+export function normalizeExtraMemoryPaths(workspaceDir, extraPaths) {
+    if (!extraPaths?.length) {
+        return [];
+    }
+    const resolved = extraPaths
+        .map((value) => value.trim())
+        .filter(Boolean)
+        .map((value) => path.isAbsolute(value) ? path.resolve(value) : path.resolve(workspaceDir, value));
+    return Array.from(new Set(resolved));
+}
+export function isMemoryPath(relPath) {
+    const normalized = normalizeRelPath(relPath);
+    if (!normalized) {
+        return false;
+    }
+    if (normalized === "MEMORY.md" || normalized === "memory.md") {
+        return true;
+    }
+    return normalized.startsWith("memory/");
+}
+async function walkDir(dir, files) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isSymbolicLink()) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            await walkDir(full, files);
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        if (!entry.name.endsWith(".md")) {
+            continue;
+        }
+        files.push(full);
+    }
+}
+export async function listMemoryFiles(workspaceDir, extraPaths) {
+    const result = [];
+    const memoryFile = path.join(workspaceDir, "MEMORY.md");
+    const altMemoryFile = path.join(workspaceDir, "memory.md");
+    const memoryDir = path.join(workspaceDir, "memory");
+    const addMarkdownFile = async (absPath) => {
+        try {
+            const stat = await fs.lstat(absPath);
+            if (stat.isSymbolicLink() || !stat.isFile()) {
+                return;
+            }
+            if (!absPath.endsWith(".md")) {
+                return;
+            }
+            result.push(absPath);
+        }
+        catch { }
+    };
+    await addMarkdownFile(memoryFile);
+    await addMarkdownFile(altMemoryFile);
+    try {
+        const dirStat = await fs.lstat(memoryDir);
+        if (!dirStat.isSymbolicLink() && dirStat.isDirectory()) {
+            await walkDir(memoryDir, result);
+        }
+    }
+    catch { }
+    const normalizedExtraPaths = normalizeExtraMemoryPaths(workspaceDir, extraPaths);
+    if (normalizedExtraPaths.length > 0) {
+        for (const inputPath of normalizedExtraPaths) {
+            try {
+                const stat = await fs.lstat(inputPath);
+                if (stat.isSymbolicLink()) {
+                    continue;
+                }
+                if (stat.isDirectory()) {
+                    await walkDir(inputPath, result);
+                    continue;
+                }
+                if (stat.isFile() && inputPath.endsWith(".md")) {
+                    result.push(inputPath);
+                }
+            }
+            catch { }
+        }
+    }
+    if (result.length <= 1) {
+        return result;
+    }
+    const seen = new Set();
+    const deduped = [];
+    for (const entry of result) {
+        let key = entry;
+        try {
+            key = await fs.realpath(entry);
+        }
+        catch { }
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        deduped.push(entry);
+    }
+    return deduped;
+}
+export function hashText(value) {
+    return crypto.createHash("sha256").update(value).digest("hex");
+}
+export async function buildFileEntry(absPath, workspaceDir) {
+    const stat = await fs.stat(absPath);
+    const content = await fs.readFile(absPath, "utf-8");
+    const hash = hashText(content);
+    return {
+        path: path.relative(workspaceDir, absPath).replace(/\\/g, "/"),
+        absPath,
+        mtimeMs: stat.mtimeMs,
+        size: stat.size,
+        hash,
+    };
+}
+export function chunkMarkdown(content, chunking) {
+    const lines = content.split("\n");
+    if (lines.length === 0) {
+        return [];
+    }
+    const maxChars = Math.max(32, chunking.tokens * 4);
+    const overlapChars = Math.max(0, chunking.overlap * 4);
+    const chunks = [];
+    let current = [];
+    let currentChars = 0;
+    const flush = () => {
+        if (current.length === 0) {
+            return;
+        }
+        const firstEntry = current[0];
+        const lastEntry = current[current.length - 1];
+        if (!firstEntry || !lastEntry) {
+            return;
+        }
+        const text = current.map((entry) => entry.line).join("\n");
+        const startLine = firstEntry.lineNo;
+        const endLine = lastEntry.lineNo;
+        chunks.push({
+            startLine,
+            endLine,
+            text,
+            hash: hashText(text),
+        });
+    };
+    const carryOverlap = () => {
+        if (overlapChars <= 0 || current.length === 0) {
+            current = [];
+            currentChars = 0;
+            return;
+        }
+        let acc = 0;
+        const kept = [];
+        for (let i = current.length - 1; i >= 0; i -= 1) {
+            const entry = current[i];
+            if (!entry) {
+                continue;
+            }
+            acc += entry.line.length + 1;
+            kept.unshift(entry);
+            if (acc >= overlapChars) {
+                break;
+            }
+        }
+        current = kept;
+        currentChars = kept.reduce((sum, entry) => sum + entry.line.length + 1, 0);
+    };
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? "";
+        const lineNo = i + 1;
+        const segments = [];
+        if (line.length === 0) {
+            segments.push("");
+        }
+        else {
+            for (let start = 0; start < line.length; start += maxChars) {
+                segments.push(line.slice(start, start + maxChars));
+            }
+        }
+        for (const segment of segments) {
+            const lineSize = segment.length + 1;
+            if (currentChars + lineSize > maxChars && current.length > 0) {
+                flush();
+                carryOverlap();
+            }
+            current.push({ line: segment, lineNo });
+            currentChars += lineSize;
+        }
+    }
+    flush();
+    return chunks;
+}
+export function parseEmbedding(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function cosineSimilarity(a, b) {
+    if (a.length === 0 || b.length === 0) {
+        return 0;
+    }
+    const len = Math.min(a.length, b.length);
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < len; i += 1) {
+        const av = a[i] ?? 0;
+        const bv = b[i] ?? 0;
+        dot += av * bv;
+        normA += av * av;
+        normB += bv * bv;
+    }
+    if (normA === 0 || normB === 0) {
+        return 0;
+    }
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}

package/dist/memory/manager-cache-key.d.ts

@@ -0,0 +1,6 @@
+import type { ResolvedMemorySearchConfig } from "../agents/memory-search.js";
+export declare function computeMemoryManagerCacheKey(params: {
+    agentId: string;
+    workspaceDir: string;
+    settings: ResolvedMemorySearchConfig;
+}): string;

package/dist/memory/manager-cache-key.js

@@ -0,0 +1,46 @@
+import { fingerprintHeaderNames } from "./headers-fingerprint.js";
+import { hashText } from "./internal.js";
+export function computeMemoryManagerCacheKey(params) {
+    const settings = params.settings;
+    const fingerprint = hashText(JSON.stringify({
+        enabled: settings.enabled,
+        sources: [...settings.sources].toSorted((a, b) => a.localeCompare(b)),
+        extraPaths: [...settings.extraPaths].toSorted((a, b) => a.localeCompare(b)),
+        provider: settings.provider,
+        model: settings.model,
+        fallback: settings.fallback,
+        local: {
+            modelPath: settings.local.modelPath,
+            modelCacheDir: settings.local.modelCacheDir,
+        },
+        remote: settings.remote
+            ? {
+                baseUrl: settings.remote.baseUrl,
+                headerNames: fingerprintHeaderNames(settings.remote.headers),
+                batch: settings.remote.batch
+                    ? {
+                        enabled: settings.remote.batch.enabled,
+                        wait: settings.remote.batch.wait,
+                        concurrency: settings.remote.batch.concurrency,
+                        pollIntervalMs: settings.remote.batch.pollIntervalMs,
+                        timeoutMinutes: settings.remote.batch.timeoutMinutes,
+                    }
+                    : undefined,
+            }
+            : undefined,
+        experimental: settings.experimental,
+        store: {
+            driver: settings.store.driver,
+            path: settings.store.path,
+            vector: {
+                enabled: settings.store.vector.enabled,
+                extensionPath: settings.store.vector.extensionPath,
+            },
+        },
+        chunking: settings.chunking,
+        sync: settings.sync,
+        query: settings.query,
+        cache: settings.cache,
+    }));
+    return `${params.agentId}:${params.workspaceDir}:${fingerprint}`;
+}

package/dist/memory/manager-search.d.ts

@@ -0,0 +1,60 @@
+import type { DatabaseSync } from "node:sqlite";
+export type SearchSource = string;
+export type SearchRowResult = {
+    id: string;
+    path: string;
+    startLine: number;
+    endLine: number;
+    score: number;
+    snippet: string;
+    source: SearchSource;
+};
+export declare function searchVector(params: {
+    db: DatabaseSync;
+    vectorTable: string;
+    providerModel: string;
+    queryVec: number[];
+    limit: number;
+    snippetMaxChars: number;
+    ensureVectorReady: (dimensions: number) => Promise<boolean>;
+    sourceFilterVec: {
+        sql: string;
+        params: SearchSource[];
+    };
+    sourceFilterChunks: {
+        sql: string;
+        params: SearchSource[];
+    };
+}): Promise<SearchRowResult[]>;
+export declare function listChunks(params: {
+    db: DatabaseSync;
+    providerModel: string;
+    sourceFilter: {
+        sql: string;
+        params: SearchSource[];
+    };
+}): Array<{
+    id: string;
+    path: string;
+    startLine: number;
+    endLine: number;
+    text: string;
+    embedding: number[];
+    source: SearchSource;
+}>;
+export declare function searchKeyword(params: {
+    db: DatabaseSync;
+    ftsTable: string;
+    providerModel: string;
+    query: string;
+    limit: number;
+    snippetMaxChars: number;
+    sourceFilter: {
+        sql: string;
+        params: SearchSource[];
+    };
+    buildFtsQuery: (raw: string) => string | null;
+    bm25RankToScore: (rank: number) => number;
+}): Promise<Array<SearchRowResult & {
+    textScore: number;
+}>>;