agentikit 0.0.13 → 0.0.15

package/dist/{src/db.js → db.js}

@@ -1,15 +1,13 @@
+import { Database } from "bun:sqlite";
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
-import { Database } from "bun:sqlite";
+import { cosineSimilarity } from "./embedder";
+import { getDbPath } from "./paths";
+import { warn } from "./warn";
 // ── Constants ───────────────────────────────────────────────────────────────
-export const DB_VERSION = 5;
+export const DB_VERSION = 6;
 export const EMBEDDING_DIM = 384;
-// ── Path ────────────────────────────────────────────────────────────────────
-export function getDbPath() {
-    const cacheDir = process.env.XDG_CACHE_HOME ||
-        path.join(process.env.HOME || process.env.USERPROFILE || "", ".cache");
-    return path.join(cacheDir, "agentikit", "index.db");
-}
 // ── Database lifecycle ──────────────────────────────────────────────────────
 export function openDatabase(dbPath, options) {
     const resolvedPath = dbPath ?? getDbPath();
@@ -23,26 +21,53 @@ export function openDatabase(dbPath, options) {
     // Try to load sqlite-vec extension
     loadVecExtension(db);
     ensureSchema(db, options?.embeddingDim ?? EMBEDDING_DIM);
+    // Warn once at init if using JS fallback with many entries
+    warnIfVecMissing(db, { once: true });
     return db;
 }
 export function closeDatabase(db) {
     db.close();
 }
 // ── sqlite-vec extension ────────────────────────────────────────────────────
-let vecAvailable = false;
+const vecStatus = new WeakMap();
 function loadVecExtension(db) {
     try {
-        const sqliteVec = require("sqlite-vec");
+        const esmRequire = createRequire(import.meta.url);
+        const sqliteVec = esmRequire("sqlite-vec");
         sqliteVec.load(db);
-        vecAvailable = true;
+        vecStatus.set(db, true);
     }
     catch {
-        console.warn("sqlite-vec extension not available, embeddings will be skipped");
-        vecAvailable = false;
+        vecStatus.set(db, false);
     }
 }
-export function isVecAvailable() {
-    return vecAvailable;
+export function isVecAvailable(db) {
+    return vecStatus.get(db) ?? false;
+}
+const VEC_DOCS_URL = "https://github.com/itlackey/agentikit/blob/main/docs/configuration.md#sqlite-vec-extension";
+const VEC_FALLBACK_THRESHOLD = 10_000;
+let vecInitWarned = false;
+/**
+ * Warn if sqlite-vec is unavailable and embedding count exceeds threshold.
+ * Called from openDatabase (once at init) and from indexer (each run).
+ */
+export function warnIfVecMissing(db, { once } = { once: false }) {
+    if (isVecAvailable(db))
+        return;
+    if (once && vecInitWarned)
+        return;
+    try {
+        const row = db.prepare("SELECT COUNT(*) AS cnt FROM embeddings").get();
+        const count = row?.cnt ?? 0;
+        if (count >= VEC_FALLBACK_THRESHOLD) {
+            warn("Semantic search is using JS fallback for %d entries. Install sqlite-vec for faster performance.\n  See: %s", count, VEC_DOCS_URL);
+            if (once)
+                vecInitWarned = true;
+        }
+    }
+    catch {
+        /* embeddings table may not exist yet during init */
+    }
 }
 // ── Schema ──────────────────────────────────────────────────────────────────
 function ensureSchema(db, embeddingDim) {
@@ -56,6 +81,7 @@ function ensureSchema(db, embeddingDim) {
     // Check stored version — if it differs from DB_VERSION, drop and recreate all tables
     const storedVersion = getMeta(db, "version");
     if (storedVersion && storedVersion !== String(DB_VERSION)) {
+        db.exec("DROP TABLE IF EXISTS embeddings");
         db.exec("DROP TABLE IF EXISTS entries_vec");
         db.exec("DROP TABLE IF EXISTS entries_fts");
         db.exec("DROP INDEX IF EXISTS idx_entries_dir");
@@ -77,11 +103,17 @@ function ensureSchema(db, embeddingDim) {
 
     CREATE INDEX IF NOT EXISTS idx_entries_dir ON entries(dir_path);
     CREATE INDEX IF NOT EXISTS idx_entries_type ON entries(entry_type);
+  `);
+    // BLOB-based embedding storage (always available, no sqlite-vec needed)
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS embeddings (
+      id        INTEGER PRIMARY KEY,
+      embedding BLOB NOT NULL,
+      FOREIGN KEY (id) REFERENCES entries(id)
+    );
   `);
     // FTS5 table — standalone with explicit entry_id for joining
-    const ftsExists = db
-        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='entries_fts'")
-        .get();
+    const ftsExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='entries_fts'").get();
     if (!ftsExists) {
         db.exec(`
       CREATE VIRTUAL TABLE entries_fts USING fts5(
@@ -92,18 +124,18 @@ function ensureSchema(db, embeddingDim) {
     `);
     }
     // sqlite-vec table
-    if (vecAvailable) {
+    if (isVecAvailable(db)) {
         // Check if stored embedding dimension differs from configured one
         const storedDim = getMeta(db, "embeddingDim");
         if (storedDim && storedDim !== String(embeddingDim)) {
             try {
                 db.exec("DROP TABLE IF EXISTS entries_vec");
             }
-            catch { /* ignore */ }
+            catch {
+                /* ignore */
+            }
         }
-        const vecExists = db
-            .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='entries_vec'")
-            .get();
+        const vecExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='entries_vec'").get();
         if (!vecExists) {
             db.exec(`
         CREATE VIRTUAL TABLE entries_vec USING vec0(
@@ -147,15 +179,21 @@ export function upsertEntry(db, entryKey, dirPath, filePath, stashDir, entry, se
     return row.id;
 }
 export function deleteEntriesByDir(db, dirPath) {
-    if (vecAvailable) {
-        const ids = db
-            .prepare("SELECT id FROM entries WHERE dir_path = ?")
-            .all(dirPath);
-        for (const { id } of ids) {
+    const ids = db.prepare("SELECT id FROM entries WHERE dir_path = ?").all(dirPath);
+    for (const { id } of ids) {
+        try {
+            db.prepare("DELETE FROM embeddings WHERE id = ?").run(id);
+        }
+        catch {
+            /* ignore */
+        }
+        if (isVecAvailable(db)) {
             try {
                 db.prepare("DELETE FROM entries_vec WHERE id = ?").run(id);
             }
-            catch { /* ignore if vec table missing */ }
+            catch {
+                /* ignore */
+            }
         }
     }
     db.prepare("DELETE FROM entries WHERE dir_path = ?").run(dirPath);
@@ -166,32 +204,67 @@ export function rebuildFts(db) {
 }
 // ── Vector operations ───────────────────────────────────────────────────────
 export function upsertEmbedding(db, entryId, embedding) {
-    if (!vecAvailable)
-        return;
     const buf = float32Buffer(embedding);
-    try {
-        db.prepare("DELETE FROM entries_vec WHERE id = ?").run(entryId);
+    // Always write to BLOB table (works without sqlite-vec)
+    db.prepare("INSERT OR REPLACE INTO embeddings (id, embedding) VALUES (?, ?)").run(entryId, buf);
+    // Also write to sqlite-vec table when available (fast path)
+    if (isVecAvailable(db)) {
+        try {
+            db.prepare("DELETE FROM entries_vec WHERE id = ?").run(entryId);
+        }
+        catch {
+            /* ignore */
+        }
+        db.prepare("INSERT INTO entries_vec (id, embedding) VALUES (?, ?)").run(entryId, buf);
     }
-    catch { /* ignore */ }
-    db.prepare("INSERT INTO entries_vec (id, embedding) VALUES (?, ?)").run(entryId, buf);
 }
 export function searchVec(db, queryEmbedding, k) {
-    if (!vecAvailable)
-        return [];
-    const buf = float32Buffer(queryEmbedding);
-    try {
-        return db
-            .prepare("SELECT id, distance FROM entries_vec WHERE embedding MATCH ? AND k = ?")
-            .all(buf, k);
-    }
-    catch {
-        return [];
+    // Fast path: use sqlite-vec when available
+    if (isVecAvailable(db)) {
+        const buf = float32Buffer(queryEmbedding);
+        try {
+            return db
+                .prepare("SELECT id, distance FROM entries_vec WHERE embedding MATCH ? AND k = ?")
+                .all(buf, k);
+        }
+        catch {
+            return [];
+        }
     }
+    // Fallback: JS-based cosine similarity over BLOB table
+    return searchBlobVec(db, queryEmbedding, k);
 }
 function float32Buffer(vec) {
     const f32 = new Float32Array(vec);
     return Buffer.from(f32.buffer);
 }
+function bufferToFloat32(buf) {
+    const f32 = new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
+    return Array.from(f32);
+}
+function searchBlobVec(db, queryEmbedding, k) {
+    try {
+        const rows = db.prepare("SELECT id, embedding FROM embeddings").all();
+        if (rows.length === 0)
+            return [];
+        const scored = [];
+        for (const row of rows) {
+            const embedding = bufferToFloat32(row.embedding);
+            const similarity = cosineSimilarity(queryEmbedding, embedding);
+            scored.push({ id: row.id, similarity });
+        }
+        scored.sort((a, b) => b.similarity - a.similarity);
+        // Convert cosine similarity to L2 distance for compatibility with sqlite-vec interface
+        // For normalized vectors: L2² = 2(1 - cos_sim)
+        return scored.slice(0, k).map(({ id, similarity }) => ({
+            id,
+            distance: Math.sqrt(2 * Math.max(0, 1 - similarity)),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
 // ── FTS5 search ─────────────────────────────────────────────────────────────
 export function searchFts(db, query, limit, entryType) {
     const ftsQuery = sanitizeFtsQuery(query);
@@ -242,18 +315,19 @@ function sanitizeFtsQuery(query) {
     const tokens = query
         .replace(/[^a-zA-Z0-9\s]/g, " ")
         .split(/\s+/)
-        .filter((t) => t.length > 1);
+        .filter((t) => t.length >= 1);
     if (tokens.length === 0)
         return "";
     // Use unquoted tokens so the porter stemmer can normalize word forms
-    return tokens.join(" OR ");
+    return tokens.join(" ");
 }
 // ── All entries ─────────────────────────────────────────────────────────────
 export function getAllEntries(db, entryType) {
     let sql;
     let params;
     if (entryType && entryType !== "any") {
-        sql = "SELECT id, entry_key, dir_path, file_path, stash_dir, entry_json, search_text FROM entries WHERE entry_type = ?";
+        sql =
+            "SELECT id, entry_key, dir_path, file_path, stash_dir, entry_json, search_text FROM entries WHERE entry_type = ?";
         params = [entryType];
     }
     else {
@@ -276,9 +350,7 @@ export function getEntryCount(db) {
     return row.cnt;
 }
 export function getEntryById(db, id) {
-    const row = db
-        .prepare("SELECT file_path, entry_json FROM entries WHERE id = ?")
-        .get(id);
+    const row = db.prepare("SELECT file_path, entry_json FROM entries WHERE id = ?").get(id);
     if (!row)
         return undefined;
     return { filePath: row.file_path, entry: JSON.parse(row.entry_json) };

package/dist/{src/embedder.js → embedder.js}

@@ -60,16 +60,71 @@ export async function embed(text, embeddingConfig) {
     }
     return embedLocal(text);
 }
+// ── Batch embedding ─────────────────────────────────────────────────────────
+/**
+ * Generate embeddings for multiple texts in batch.
+ * Uses the OpenAI-compatible batch API for remote endpoints (batches of 100).
+ * Falls back to sequential embedding for local transformer pipeline.
+ */
+export async function embedBatch(texts, embeddingConfig) {
+    if (texts.length === 0)
+        return [];
+    if (embeddingConfig) {
+        return embedRemoteBatch(texts, embeddingConfig);
+    }
+    // Local transformer: process sequentially (pipeline handles one at a time)
+    const results = [];
+    for (const text of texts) {
+        results.push(await embedLocal(text));
+    }
+    return results;
+}
+async function embedRemoteBatch(texts, config) {
+    const BATCH_SIZE = 100;
+    const results = [];
+    const headers = { "Content-Type": "application/json" };
+    if (config.apiKey) {
+        headers["Authorization"] = `Bearer ${config.apiKey}`;
+    }
+    for (let i = 0; i < texts.length; i += BATCH_SIZE) {
+        const batch = texts.slice(i, i + BATCH_SIZE);
+        const body = {
+            input: batch,
+            model: config.model,
+        };
+        if (config.dimension) {
+            body.dimensions = config.dimension;
+        }
+        const response = await fetchWithTimeout(config.endpoint, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const respBody = await response.text().catch(() => "");
+            throw new Error(`Embedding batch request failed (${response.status}): ${respBody}`);
+        }
+        const json = (await response.json());
+        if (!json.data || json.data.length !== batch.length) {
+            throw new Error(`Unexpected embedding batch response: expected ${batch.length} embeddings, got ${json.data?.length ?? 0}`);
+        }
+        results.push(...json.data.map((d) => d.embedding));
+    }
+    return results;
+}
 // ── Similarity ──────────────────────────────────────────────────────────────
 export function cosineSimilarity(a, b) {
     const len = Math.min(a.length, b.length);
     if (len === 0)
         return 0;
-    let dot = 0;
+    let dot = 0, magA = 0, magB = 0;
     for (let i = 0; i < len; i++) {
         dot += a[i] * b[i];
+        magA += a[i] * a[i];
+        magB += b[i] * b[i];
     }
-    return dot;
+    const denom = Math.sqrt(magA) * Math.sqrt(magB);
+    return denom === 0 ? 0 : dot / denom;
 }
 // ── Availability check ──────────────────────────────────────────────────────
 export async function isEmbeddingAvailable(embeddingConfig) {

package/dist/errors.js

@@ -0,0 +1,28 @@
+/**
+ * Typed error classes for structured exit code classification.
+ *
+ * - ConfigError  -> exit 78  (configuration / environment problems)
+ * - UsageError   -> exit 2   (bad CLI arguments or invalid input)
+ * - NotFoundError -> exit 1  (requested resource missing)
+ */
+/** Raised when configuration or environment is invalid or missing. */
+export class ConfigError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = "ConfigError";
+    }
+}
+/** Raised when the user supplies invalid arguments or input. */
+export class UsageError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = "UsageError";
+    }
+}
+/** Raised when a requested resource (asset, entry, file) is not found. */
+export class NotFoundError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = "NotFoundError";
+    }
+}

package/dist/file-context.js

@@ -0,0 +1,188 @@
+/**
+ * Flexible asset resolution system.
+ *
+ * Provides a rich FileContext built once per file during walking, plus a
+ * matcher/renderer registry that decouples asset classification from rendering.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { toPosix } from "./common";
+import { parseFrontmatter } from "./frontmatter";
+/**
+ * Build a FileContext from a stash root and an absolute file path.
+ *
+ * Path-derived fields are computed eagerly. The content, frontmatter, and
+ * stat getters use lazy caching so the file is only read from disk when
+ * (and if) a matcher or renderer actually needs it.
+ */
+export function buildFileContext(stashRoot, absPath) {
+    const relPath = toPosix(path.relative(stashRoot, absPath));
+    const ext = path.extname(absPath).toLowerCase();
+    const fileName = path.basename(absPath);
+    const parentDirAbs = path.dirname(absPath);
+    const parentDir = path.basename(parentDirAbs);
+    // Compute ancestor directory segments from the POSIX relPath's directory portion.
+    // For "tools/azure/deploy/run.sh" the dir portion is "tools/azure/deploy"
+    // which splits into ["tools", "azure", "deploy"].
+    const relDir = toPosix(path.dirname(relPath));
+    const ancestorDirs = relDir === "." ? [] : relDir.split("/").filter((seg) => seg.length > 0);
+    // Lazy caches
+    let cachedContent;
+    let cachedFrontmatter;
+    let frontmatterComputed = false;
+    let cachedStat;
+    return {
+        absPath,
+        relPath,
+        ext,
+        fileName,
+        parentDir,
+        parentDirAbs,
+        ancestorDirs,
+        stashRoot,
+        content() {
+            if (cachedContent === undefined) {
+                cachedContent = fs.readFileSync(absPath, "utf8");
+            }
+            return cachedContent;
+        },
+        frontmatter() {
+            if (!frontmatterComputed) {
+                const raw = this.content();
+                const parsed = parseFrontmatter(raw);
+                cachedFrontmatter = Object.keys(parsed.data).length > 0 ? parsed.data : null;
+                frontmatterComputed = true;
+            }
+            return cachedFrontmatter;
+        },
+        stat() {
+            if (cachedStat === undefined) {
+                cachedStat = fs.statSync(absPath);
+            }
+            return cachedStat;
+        },
+    };
+}
+// ── Registry ─────────────────────────────────────────────────────────────────
+/** Ordered list of registered matchers. Later registrations win ties. */
+const matchers = [];
+/** Renderer lookup by name. */
+const renderers = new Map();
+let builtinsInitialized = false;
+/** Pluggable initializer set via `setBuiltinRegistrar`. */
+let builtinRegistrar = null;
+/**
+ * Set the function that registers built-in matchers and renderers.
+ *
+ * This breaks the static import cycle: `file-context.ts` does not need to
+ * import `matchers.ts` or `renderers.ts` at the top level. Instead, a
+ * one-time call from outside (e.g. the test file or CLI entry) provides the
+ * registration callback.
+ *
+ * If no registrar is set by the time `ensureBuiltinsRegistered` runs, it
+ * falls back to a dynamic `require()` for backward compatibility.
+ */
+export function setBuiltinRegistrar(fn) {
+    builtinRegistrar = fn;
+}
+/**
+ * Ensure that built-in matchers and renderers are registered.
+ * Called lazily on first use of runMatchers/getRenderer.
+ *
+ * Uses the registrar set via `setBuiltinRegistrar`, or falls back to
+ * a direct import of the registration modules. The dynamic import
+ * avoids a static circular dependency between file-context, renderers,
+ * and asset-spec.
+ */
+function ensureBuiltinsRegistered() {
+    if (builtinsInitialized)
+        return;
+    builtinsInitialized = true;
+    if (builtinRegistrar) {
+        builtinRegistrar();
+        return;
+    }
+    // Lazy inline require avoids a top-level static import cycle:
+    //   file-context -> renderers -> asset-spec -> asset-type-handler -> handlers -> file-context
+    // These are only evaluated once and only when no explicit registrar was set.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { registerBuiltinMatchers } = require("./matchers");
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { registerBuiltinRenderers } = require("./renderers");
+    registerBuiltinMatchers();
+    registerBuiltinRenderers();
+}
+/**
+ * Register an AssetMatcher.
+ *
+ * Matchers are evaluated in registration order. When two matchers produce
+ * the same specificity score, the one registered later wins.
+ */
+export function registerMatcher(matcher) {
+    matchers.push(matcher);
+}
+/**
+ * Register an AssetRenderer.
+ *
+ * If a renderer with the same name already exists it is silently replaced.
+ */
+export function registerRenderer(renderer) {
+    renderers.set(renderer.name, renderer);
+}
+/**
+ * Look up a renderer by name.
+ */
+export function getRenderer(name) {
+    ensureBuiltinsRegistered();
+    return renderers.get(name);
+}
+/**
+ * Return all registered renderers (snapshot, safe to iterate).
+ */
+export function getAllRenderers() {
+    ensureBuiltinsRegistered();
+    return Array.from(renderers.values());
+}
+/**
+ * Run every registered matcher against a FileContext and return the
+ * highest-specificity result.
+ *
+ * Resolution rules:
+ * 1. Every matcher is invoked; null returns are discarded.
+ * 2. Results are ranked by specificity (descending).
+ * 3. Ties are broken by registration order: the matcher registered later wins
+ *    (this lets user-registered matchers override built-in ones).
+ * 4. Returns null when no matcher claims the file.
+ */
+export function runMatchers(ctx) {
+    ensureBuiltinsRegistered();
+    // Collect (result, registrationIndex) pairs from all matchers.
+    const hits = [];
+    for (let i = 0; i < matchers.length; i++) {
+        const result = matchers[i](ctx);
+        if (result !== null) {
+            hits.push({ result, index: i });
+        }
+    }
+    if (hits.length === 0)
+        return null;
+    // Sort by specificity descending, then by registration index descending (later wins ties).
+    hits.sort((a, b) => {
+        const specDiff = b.result.specificity - a.result.specificity;
+        if (specDiff !== 0)
+            return specDiff;
+        return b.index - a.index;
+    });
+    return hits[0].result;
+}
+/**
+ * Build a RenderContext by merging a FileContext with its winning MatchResult
+ * and the list of stash search paths.
+ */
+export function buildRenderContext(ctx, match, stashDirs) {
+    return {
+        ...ctx,
+        matchResult: match,
+        stashDirs,
+    };
+}

package/dist/{src/frontmatter.js → frontmatter.js}

@@ -18,7 +18,7 @@ export function parseFrontmatter(raw) {
     let currentKey = null;
     let nested = null;
     for (const line of parsedBlock.frontmatter.split(/\r?\n/)) {
-        const indented = line.match(/^  (\w[\w-]*):\s*(.+)$/);
+        const indented = line.match(/^ {2}(\w[\w-]*):\s*(.+)$/);
         if (indented && currentKey && nested) {
             nested[indented[1]] = parseYamlScalar(indented[2].trim());
             continue;

package/dist/{src/github.js → github.js}

@@ -10,9 +10,7 @@ export function githubHeaders() {
     return headers;
 }
 export function asRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value)
-        ? value
-        : {};
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
 }
 export function asString(value) {
     return typeof value === "string" && value ? value : undefined;

package/dist/handlers/agent-handler.js

@@ -0,0 +1,19 @@
+import { getRenderer } from "../file-context";
+import { showInputToRenderContext } from "./handler-bridge";
+import { isMarkdownFile, markdownAssetPath, markdownCanonicalName } from "./markdown-helpers";
+export const agentHandler = {
+    typeName: "agent",
+    stashDir: "agents",
+    isRelevantFile: isMarkdownFile,
+    toCanonicalName: markdownCanonicalName,
+    toAssetPath: markdownAssetPath,
+    buildShowResponse(input) {
+        const renderer = getRenderer("agent-md");
+        const ctx = showInputToRenderContext(input, "agent-md");
+        return renderer.buildShowResponse(ctx);
+    },
+    defaultUsageGuide: [
+        "Read the .md file and dispatch an agent using the content of the file. Use modelHint/toolPolicy when present to run the agent with compatible settings.",
+        "Use with `akm show <openRef>` to get the full prompt payload.",
+    ],
+};

package/dist/handlers/command-handler.js

@@ -0,0 +1,20 @@
+import { getRenderer } from "../file-context";
+import { showInputToRenderContext } from "./handler-bridge";
+import { isMarkdownFile, markdownAssetPath, markdownCanonicalName } from "./markdown-helpers";
+export const commandHandler = {
+    typeName: "command",
+    stashDir: "commands",
+    isRelevantFile: isMarkdownFile,
+    toCanonicalName: markdownCanonicalName,
+    toAssetPath: markdownAssetPath,
+    buildShowResponse(input) {
+        const renderer = getRenderer("command-md");
+        const ctx = showInputToRenderContext(input, "command-md");
+        return renderer.buildShowResponse(ctx);
+    },
+    defaultUsageGuide: [
+        "Read the .md file, fill $ARGUMENTS placeholders, and run it in the current repo context.",
+        "Use `akm show <openRef>` to retrieve the command template body.",
+        "When `agent` is specified, dispatch the command to that agent.",
+    ],
+};