agentikit 0.0.8 → 0.0.12

package/src/db.ts

@@ -0,0 +1,411 @@
+import fs from "node:fs"
+import path from "node:path"
+import { Database } from "bun:sqlite"
+import type { StashEntry } from "./metadata"
+import type { EmbeddingVector } from "./embedder"
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export interface DbIndexedEntry {
+  id: number
+  entryKey: string
+  dirPath: string
+  filePath: string
+  stashDir: string
+  entry: StashEntry
+  searchText: string
+}
+
+export interface DbSearchResult {
+  id: number
+  filePath: string
+  entry: StashEntry
+  searchText: string
+  bm25Score: number
+}
+
+export interface DbVecResult {
+  id: number
+  distance: number
+}
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+export const DB_VERSION = 5
+export const EMBEDDING_DIM = 384
+
+// ── Path ────────────────────────────────────────────────────────────────────
+
+export function getDbPath(): string {
+  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?: string, options?: { embeddingDim?: number }): Database {
+  const resolvedPath = dbPath ?? getDbPath()
+  const dir = path.dirname(resolvedPath)
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+
+  const db = new Database(resolvedPath)
+  db.exec("PRAGMA journal_mode = WAL")
+  db.exec("PRAGMA foreign_keys = ON")
+
+  // Try to load sqlite-vec extension
+  loadVecExtension(db)
+
+  ensureSchema(db, options?.embeddingDim ?? EMBEDDING_DIM)
+  return db
+}
+
+export function closeDatabase(db: Database): void {
+  db.close()
+}
+
+// ── sqlite-vec extension ────────────────────────────────────────────────────
+
+let vecAvailable = false
+
+function loadVecExtension(db: Database): void {
+  try {
+    const sqliteVec = require("sqlite-vec")
+    sqliteVec.load(db)
+    vecAvailable = true
+  } catch {
+    console.warn("sqlite-vec extension not available, embeddings will be skipped")
+    vecAvailable = false
+  }
+}
+
+export function isVecAvailable(): boolean {
+  return vecAvailable
+}
+
+// ── Schema ──────────────────────────────────────────────────────────────────
+
+function ensureSchema(db: Database, embeddingDim: number): void {
+  // Create meta table first so we can check version
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS index_meta (
+      key   TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+  `)
+
+  // 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 entries_vec")
+    db.exec("DROP TABLE IF EXISTS entries_fts")
+    db.exec("DROP INDEX IF EXISTS idx_entries_dir")
+    db.exec("DROP INDEX IF EXISTS idx_entries_type")
+    db.exec("DROP TABLE IF EXISTS entries")
+    db.exec("DELETE FROM index_meta")
+  }
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS entries (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      entry_key   TEXT NOT NULL UNIQUE,
+      dir_path    TEXT NOT NULL,
+      file_path   TEXT NOT NULL,
+      stash_dir   TEXT NOT NULL,
+      entry_json  TEXT NOT NULL,
+      search_text TEXT NOT NULL,
+      entry_type  TEXT NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_entries_dir ON entries(dir_path);
+    CREATE INDEX IF NOT EXISTS idx_entries_type ON entries(entry_type);
+  `)
+
+  // 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()
+  if (!ftsExists) {
+    db.exec(`
+      CREATE VIRTUAL TABLE entries_fts USING fts5(
+        entry_id UNINDEXED,
+        search_text,
+        tokenize='porter unicode61'
+      );
+    `)
+  }
+
+  // sqlite-vec table
+  if (vecAvailable) {
+    // 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 */ }
+    }
+
+    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(
+          id       INTEGER PRIMARY KEY,
+          embedding FLOAT[${embeddingDim}]
+        );
+      `)
+    }
+    setMeta(db, "embeddingDim", String(embeddingDim))
+  }
+
+  // Set version if not present
+  const version = getMeta(db, "version")
+  if (!version) {
+    setMeta(db, "version", String(DB_VERSION))
+  }
+}
+
+// ── Meta helpers ────────────────────────────────────────────────────────────
+
+export function getMeta(db: Database, key: string): string | undefined {
+  const row = db.prepare("SELECT value FROM index_meta WHERE key = ?").get(key) as
+    | { value: string }
+    | undefined
+  return row?.value
+}
+
+export function setMeta(db: Database, key: string, value: string): void {
+  db.prepare("INSERT OR REPLACE INTO index_meta (key, value) VALUES (?, ?)").run(key, value)
+}
+
+// ── Entry operations ────────────────────────────────────────────────────────
+
+export function upsertEntry(
+  db: Database,
+  entryKey: string,
+  dirPath: string,
+  filePath: string,
+  stashDir: string,
+  entry: StashEntry,
+  searchText: string,
+): number {
+  const stmt = db.prepare(`
+    INSERT INTO entries (entry_key, dir_path, file_path, stash_dir, entry_json, search_text, entry_type)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(entry_key) DO UPDATE SET
+      dir_path = excluded.dir_path,
+      file_path = excluded.file_path,
+      stash_dir = excluded.stash_dir,
+      entry_json = excluded.entry_json,
+      search_text = excluded.search_text,
+      entry_type = excluded.entry_type
+  `)
+  stmt.run(entryKey, dirPath, filePath, stashDir, JSON.stringify(entry), searchText, entry.type)
+  // Fetch the row id explicitly since last_insert_rowid() is unreliable for ON CONFLICT DO UPDATE
+  const row = db.prepare("SELECT id FROM entries WHERE entry_key = ?").get(entryKey) as { id: number }
+  return row.id
+}
+
+export function deleteEntriesByDir(db: Database, dirPath: string): void {
+  if (vecAvailable) {
+    const ids = db
+      .prepare("SELECT id FROM entries WHERE dir_path = ?")
+      .all(dirPath) as Array<{ id: number }>
+    for (const { id } of ids) {
+      try {
+        db.prepare("DELETE FROM entries_vec WHERE id = ?").run(id)
+      } catch { /* ignore if vec table missing */ }
+    }
+  }
+  db.prepare("DELETE FROM entries WHERE dir_path = ?").run(dirPath)
+}
+
+export function rebuildFts(db: Database): void {
+  db.exec("DELETE FROM entries_fts")
+  db.exec("INSERT INTO entries_fts (entry_id, search_text) SELECT CAST(id AS TEXT), search_text FROM entries")
+}
+
+// ── Vector operations ───────────────────────────────────────────────────────
+
+export function upsertEmbedding(
+  db: Database,
+  entryId: number,
+  embedding: EmbeddingVector,
+): void {
+  if (!vecAvailable) return
+  const buf = float32Buffer(embedding)
+  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)
+}
+
+export function searchVec(
+  db: Database,
+  queryEmbedding: EmbeddingVector,
+  k: number,
+): DbVecResult[] {
+  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) as DbVecResult[]
+  } catch {
+    return []
+  }
+}
+
+function float32Buffer(vec: number[]): Buffer {
+  const f32 = new Float32Array(vec)
+  return Buffer.from(f32.buffer)
+}
+
+// ── FTS5 search ─────────────────────────────────────────────────────────────
+
+export function searchFts(
+  db: Database,
+  query: string,
+  limit: number,
+  entryType?: string,
+): DbSearchResult[] {
+  const ftsQuery = sanitizeFtsQuery(query)
+  if (!ftsQuery) return []
+
+  let sql: string
+  let params: unknown[]
+
+  if (entryType && entryType !== "any") {
+    sql = `
+      SELECT e.id, e.file_path AS filePath, e.entry_json, e.search_text AS searchText,
+             bm25(entries_fts) AS bm25Score
+      FROM entries_fts f
+      JOIN entries e ON e.id = CAST(f.entry_id AS INTEGER)
+      WHERE entries_fts MATCH ?
+        AND e.entry_type = ?
+      ORDER BY bm25Score
+      LIMIT ?
+    `
+    params = [ftsQuery, entryType, limit]
+  } else {
+    sql = `
+      SELECT e.id, e.file_path AS filePath, e.entry_json, e.search_text AS searchText,
+             bm25(entries_fts) AS bm25Score
+      FROM entries_fts f
+      JOIN entries e ON e.id = CAST(f.entry_id AS INTEGER)
+      WHERE entries_fts MATCH ?
+      ORDER BY bm25Score
+      LIMIT ?
+    `
+    params = [ftsQuery, limit]
+  }
+
+  try {
+    const rows = db.prepare(sql).all(...(params as import("bun:sqlite").SQLQueryBindings[])) as Array<{
+      id: number
+      filePath: string
+      entry_json: string
+      searchText: string
+      bm25Score: number
+    }>
+
+    return rows.map((row) => ({
+      id: row.id,
+      filePath: row.filePath,
+      entry: JSON.parse(row.entry_json) as StashEntry,
+      searchText: row.searchText,
+      bm25Score: row.bm25Score,
+    }))
+  } catch {
+    return []
+  }
+}
+
+function sanitizeFtsQuery(query: string): string {
+  const tokens = query
+    .replace(/[^a-zA-Z0-9\s]/g, " ")
+    .split(/\s+/)
+    .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 ")
+}
+
+// ── All entries ─────────────────────────────────────────────────────────────
+
+export function getAllEntries(
+  db: Database,
+  entryType?: string,
+): DbIndexedEntry[] {
+  let sql: string
+  let params: unknown[]
+
+  if (entryType && entryType !== "any") {
+    sql = "SELECT id, entry_key, dir_path, file_path, stash_dir, entry_json, search_text FROM entries WHERE entry_type = ?"
+    params = [entryType]
+  } else {
+    sql = "SELECT id, entry_key, dir_path, file_path, stash_dir, entry_json, search_text FROM entries"
+    params = []
+  }
+
+  const rows = db.prepare(sql).all(...(params as import("bun:sqlite").SQLQueryBindings[])) as Array<{
+    id: number
+    entry_key: string
+    dir_path: string
+    file_path: string
+    stash_dir: string
+    entry_json: string
+    search_text: string
+  }>
+
+  return rows.map((row) => ({
+    id: row.id,
+    entryKey: row.entry_key,
+    dirPath: row.dir_path,
+    filePath: row.file_path,
+    stashDir: row.stash_dir,
+    entry: JSON.parse(row.entry_json) as StashEntry,
+    searchText: row.search_text,
+  }))
+}
+
+export function getEntryCount(db: Database): number {
+  const row = db.prepare("SELECT COUNT(*) AS cnt FROM entries").get() as { cnt: number }
+  return row.cnt
+}
+
+export function getEntryById(db: Database, id: number): { filePath: string; entry: StashEntry } | undefined {
+  const row = db
+    .prepare("SELECT file_path, entry_json FROM entries WHERE id = ?")
+    .get(id) as { file_path: string; entry_json: string } | undefined
+  if (!row) return undefined
+  return { filePath: row.file_path, entry: JSON.parse(row.entry_json) as StashEntry }
+}
+
+export function getEntriesByDir(db: Database, dirPath: string): DbIndexedEntry[] {
+  const rows = db
+    .prepare(
+      "SELECT id, entry_key, dir_path, file_path, stash_dir, entry_json, search_text FROM entries WHERE dir_path = ?",
+    )
+    .all(dirPath) as Array<{
+    id: number
+    entry_key: string
+    dir_path: string
+    file_path: string
+    stash_dir: string
+    entry_json: string
+    search_text: string
+  }>
+
+  return rows.map((row) => ({
+    id: row.id,
+    entryKey: row.entry_key,
+    dirPath: row.dir_path,
+    filePath: row.file_path,
+    stashDir: row.stash_dir,
+    entry: JSON.parse(row.entry_json) as StashEntry,
+    searchText: row.search_text,
+  }))
+}

package/src/embedder.ts

@@ -1,4 +1,5 @@
 import type { EmbeddingConnectionConfig } from "./config"
+import { fetchWithTimeout } from "./common"
 
 // ── Types ───────────────────────────────────────────────────────────────────
 
@@ -6,22 +7,27 @@ export type EmbeddingVector = number[]
 
 // ── Singleton local embedder ────────────────────────────────────────────────
 
-let localEmbedder: any
+interface TransformerPipeline {
+  (text: string, options: { pooling: string; normalize: boolean }): Promise<{ data: Float32Array }>
+}
+
+let localEmbedder: TransformerPipeline | undefined
 
-async function getLocalEmbedder(): Promise<any> {
+async function getLocalEmbedder(): Promise<TransformerPipeline> {
   if (!localEmbedder) {
-    let pipeline: any
+    let pipeline: unknown
     try {
       const mod = await import("@xenova/transformers")
-      pipeline = mod.pipeline
+      pipeline = mod.pipeline as unknown
     } catch {
       throw new Error(
         "Semantic search requires @xenova/transformers. Install it with: npm install @xenova/transformers",
       )
     }
-    localEmbedder = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2")
+    const pipelineFn = pipeline as (task: string, model: string) => Promise<TransformerPipeline>
+    localEmbedder = await pipelineFn("feature-extraction", "Xenova/all-MiniLM-L6-v2")
   }
-  return localEmbedder
+  return localEmbedder!
 }
 
 async function embedLocal(text: string): Promise<EmbeddingVector> {
@@ -41,13 +47,18 @@ async function embedRemote(
     headers["Authorization"] = `Bearer ${config.apiKey}`
   }
 
-  const response = await fetch(config.endpoint, {
+  const body: { input: string; model: string; dimensions?: number } = {
+    input: text,
+    model: config.model,
+  }
+  if (config.dimension) {
+    body.dimensions = config.dimension
+  }
+
+  const response = await fetchWithTimeout(config.endpoint, {
     method: "POST",
     headers,
-    body: JSON.stringify({
-      input: text,
-      model: config.model,
-    }),
+    body: JSON.stringify(body),
   })
 
   if (!response.ok) {

package/src/github.ts

@@ -0,0 +1,21 @@
+export const GITHUB_API_BASE = "https://api.github.com"
+
+export function githubHeaders(): HeadersInit {
+  const token = process.env.GITHUB_TOKEN?.trim()
+  const headers: Record<string, string> = {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "agentikit-registry",
+  }
+  if (token) headers.Authorization = `Bearer ${token}`
+  return headers
+}
+
+export function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {}
+}
+
+export function asString(value: unknown): string | undefined {
+  return typeof value === "string" && value ? value : undefined
+}

package/src/handlers/agent-handler.ts

@@ -0,0 +1,32 @@
+import { parseFrontmatter, toStringOrUndefined } from "../frontmatter"
+import { isMarkdownFile, markdownCanonicalName, markdownAssetPath } from "./markdown-helpers"
+import type { AssetTypeHandler, ShowInput } from "../asset-type-handler"
+import type { ShowResponse } from "../stash-types"
+
+export const agentHandler: AssetTypeHandler = {
+  typeName: "agent",
+  stashDir: "agents",
+
+  isRelevantFile: isMarkdownFile,
+  toCanonicalName: markdownCanonicalName,
+  toAssetPath: markdownAssetPath,
+
+  buildShowResponse(input: ShowInput): ShowResponse {
+    const parsedMd = parseFrontmatter(input.content)
+    return {
+      type: "agent",
+      name: input.name,
+      path: input.path,
+      description: toStringOrUndefined(parsedMd.data.description),
+      prompt: "Dispatching prompt must include the agent's full prompt content verbatim; summaries are non-compliant. \n\n"
+        + parsedMd.content,
+      toolPolicy: parsedMd.data.tools,
+      modelHint: parsedMd.data.model,
+    }
+  },
+
+  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/src/handlers/command-handler.ts

@@ -0,0 +1,29 @@
+import { parseFrontmatter, toStringOrUndefined } from "../frontmatter"
+import { isMarkdownFile, markdownCanonicalName, markdownAssetPath } from "./markdown-helpers"
+import type { AssetTypeHandler, ShowInput } from "../asset-type-handler"
+import type { ShowResponse } from "../stash-types"
+
+export const commandHandler: AssetTypeHandler = {
+  typeName: "command",
+  stashDir: "commands",
+
+  isRelevantFile: isMarkdownFile,
+  toCanonicalName: markdownCanonicalName,
+  toAssetPath: markdownAssetPath,
+
+  buildShowResponse(input: ShowInput): ShowResponse {
+    const parsedMd = parseFrontmatter(input.content)
+    return {
+      type: "command",
+      name: input.name,
+      path: input.path,
+      description: toStringOrUndefined(parsedMd.data.description),
+      template: parsedMd.content,
+    }
+  },
+
+  defaultUsageGuide: [
+    "Read the .md file, fill placeholders, and run it in the current repo context.",
+    "Use `akm show <openRef>` to retrieve the command template body.",
+  ],
+}

package/src/handlers/index.ts

@@ -0,0 +1,25 @@
+import { registerAssetType } from "../asset-type-handler"
+import { toolHandler } from "./tool-handler"
+import { skillHandler } from "./skill-handler"
+import { commandHandler } from "./command-handler"
+import { agentHandler } from "./agent-handler"
+import { knowledgeHandler } from "./knowledge-handler"
+import { scriptHandler } from "./script-handler"
+
+/**
+ * Register all built-in asset type handlers.
+ * This must be called (imported) before any handler lookups.
+ */
+registerAssetType(toolHandler)
+registerAssetType(skillHandler)
+registerAssetType(commandHandler)
+registerAssetType(agentHandler)
+registerAssetType(knowledgeHandler)
+registerAssetType(scriptHandler)
+
+export { toolHandler } from "./tool-handler"
+export { skillHandler } from "./skill-handler"
+export { commandHandler } from "./command-handler"
+export { agentHandler } from "./agent-handler"
+export { knowledgeHandler } from "./knowledge-handler"
+export { scriptHandler } from "./script-handler"

package/src/handlers/knowledge-handler.ts

@@ -0,0 +1,62 @@
+import fs from "node:fs"
+import { parseMarkdownToc, extractSection, extractLineRange, extractFrontmatterOnly, formatToc } from "../markdown"
+import { isMarkdownFile, markdownCanonicalName, markdownAssetPath } from "./markdown-helpers"
+import type { AssetTypeHandler, ShowInput } from "../asset-type-handler"
+import type { ShowResponse } from "../stash-types"
+import type { StashEntry } from "../metadata"
+
+export const knowledgeHandler: AssetTypeHandler = {
+  typeName: "knowledge",
+  stashDir: "knowledge",
+
+  isRelevantFile: isMarkdownFile,
+  toCanonicalName: markdownCanonicalName,
+  toAssetPath: markdownAssetPath,
+
+  buildShowResponse(input: ShowInput): ShowResponse {
+    const v = input.view ?? { mode: "full" }
+    switch (v.mode) {
+      case "toc": {
+        const toc = parseMarkdownToc(input.content)
+        return { type: "knowledge", name: input.name, path: input.path, content: formatToc(toc) }
+      }
+      case "frontmatter": {
+        const fm = extractFrontmatterOnly(input.content)
+        return { type: "knowledge", name: input.name, path: input.path, content: fm ?? "(no frontmatter)" }
+      }
+      case "section": {
+        const section = extractSection(input.content, v.heading)
+        if (!section) {
+          return {
+            type: "knowledge",
+            name: input.name,
+            path: input.path,
+            content: `Section "${v.heading}" not found in ${input.name}. Try --view toc to discover available headings.`,
+          }
+        }
+        return { type: "knowledge", name: input.name, path: input.path, content: section.content }
+      }
+      case "lines": {
+        return { type: "knowledge", name: input.name, path: input.path, content: extractLineRange(input.content, v.start, v.end) }
+      }
+      default: {
+        return { type: "knowledge", name: input.name, path: input.path, content: input.content }
+      }
+    }
+  },
+
+  defaultUsageGuide: [
+    "Use `akm show <openRef>` to read the document; start with `--view toc` for large files.",
+    "Use `--view section` or `--view lines` to load only the part you need.",
+  ],
+
+  extractTypeMetadata(entry: StashEntry, file: string): void {
+    try {
+      const mdContent = fs.readFileSync(file, "utf8")
+      const toc = parseMarkdownToc(mdContent)
+      if (toc.headings.length > 0) entry.toc = toc.headings
+    } catch {
+      // Non-fatal: skip TOC if file can't be read
+    }
+  },
+}

package/src/handlers/markdown-helpers.ts

@@ -0,0 +1,19 @@
+import path from "node:path"
+import { toPosix } from "../common"
+
+/**
+ * Shared file-system helpers for markdown-based asset types
+ * (command, agent, knowledge).
+ */
+
+export function isMarkdownFile(fileName: string): boolean {
+  return path.extname(fileName).toLowerCase() === ".md"
+}
+
+export function markdownCanonicalName(typeRoot: string, filePath: string): string | undefined {
+  return toPosix(path.relative(typeRoot, filePath))
+}
+
+export function markdownAssetPath(typeRoot: string, name: string): string {
+  return path.join(typeRoot, name)
+}