agentikit 0.0.7 → 0.0.9

package/src/common.ts

@@ -0,0 +1,58 @@
+import fs from "node:fs"
+import path from "node:path"
+import { TYPE_DIRS } from "./asset-spec"
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export type AgentikitAssetType = "tool" | "skill" | "command" | "agent" | "knowledge"
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+export const IS_WINDOWS = process.platform === "win32"
+export { SCRIPT_EXTENSIONS, TYPE_DIRS } from "./asset-spec"
+
+// ── Validators ──────────────────────────────────────────────────────────────
+
+export function isAssetType(type: string): type is AgentikitAssetType {
+  return type in TYPE_DIRS
+}
+
+// ── Utilities ───────────────────────────────────────────────────────────────
+
+export function resolveStashDir(): string {
+  const raw = process.env.AGENTIKIT_STASH_DIR?.trim()
+  if (!raw) {
+    throw new Error("AGENTIKIT_STASH_DIR is not set. Set it to your Agentikit stash path.")
+  }
+  const stashDir = path.resolve(raw)
+  let stat: fs.Stats
+  try {
+    stat = fs.statSync(stashDir)
+  } catch {
+    throw new Error(`Unable to read AGENTIKIT_STASH_DIR at "${stashDir}".`)
+  }
+  if (!stat.isDirectory()) {
+    throw new Error(`AGENTIKIT_STASH_DIR must point to a directory: "${stashDir}".`)
+  }
+  return stashDir
+}
+
+export function toPosix(input: string): string {
+  return input.replace(/\\/g, "/")
+}
+
+export function hasErrnoCode(error: unknown, code: string): boolean {
+  if (typeof error !== "object" || error === null || !("code" in error)) return false
+  return (error as Record<string, unknown>).code === code
+}
+
+export function isWithin(candidate: string, root: string): boolean {
+  const normalizedRoot = normalizeFsPathForComparison(path.resolve(root))
+  const normalizedCandidate = normalizeFsPathForComparison(path.resolve(candidate))
+  const rel = path.relative(normalizedRoot, normalizedCandidate)
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))
+}
+
+function normalizeFsPathForComparison(value: string): string {
+  return process.platform === "win32" ? value.toLowerCase() : value
+}

package/src/config.ts

@@ -0,0 +1,183 @@
+import fs from "node:fs"
+import path from "node:path"
+import { resolveStashDir } from "./common"
+import type { RegistryInstalledEntry, RegistrySource } from "./registry-types"
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export interface EmbeddingConnectionConfig {
+  /** OpenAI-compatible embeddings endpoint (e.g. "http://localhost:11434/v1/embeddings") */
+  endpoint: string
+  /** Model name to use for embeddings (e.g. "nomic-embed-text") */
+  model: string
+  /** Optional API key for authenticated endpoints */
+  apiKey?: string
+}
+
+export interface LlmConnectionConfig {
+  /** OpenAI-compatible chat completions endpoint (e.g. "http://localhost:11434/v1/chat/completions") */
+  endpoint: string
+  /** Model name to use (e.g. "llama3.2") */
+  model: string
+  /** Optional API key for authenticated endpoints */
+  apiKey?: string
+}
+
+export interface AgentikitConfig {
+  /** Whether semantic search is enabled. Default: true */
+  semanticSearch: boolean
+  /** Additional stash directories to search alongside the primary one */
+  additionalStashDirs: string[]
+  /** OpenAI-compatible embedding endpoint config. If not set, uses local @xenova/transformers */
+  embedding?: EmbeddingConnectionConfig
+  /** OpenAI-compatible LLM endpoint config for metadata generation. If not set, uses heuristic generation */
+  llm?: LlmConnectionConfig
+  /** Installed registry sources and local cache metadata */
+  registry?: RegistryConfig
+}
+
+export interface RegistryConfig {
+  installed: RegistryInstalledEntry[]
+}
+
+// ── Defaults ────────────────────────────────────────────────────────────────
+
+export const DEFAULT_CONFIG: AgentikitConfig = {
+  semanticSearch: true,
+  additionalStashDirs: [],
+}
+
+// ── Paths ───────────────────────────────────────────────────────────────────
+
+export function getConfigPath(stashDir: string): string {
+  return path.join(stashDir, "config.json")
+}
+
+// ── Load / Save / Update ────────────────────────────────────────────────────
+
+export function loadConfig(stashDir?: string): AgentikitConfig {
+  const dir = stashDir ?? resolveStashDir()
+  const configPath = getConfigPath(dir)
+
+  let raw: Record<string, unknown>
+  try {
+    raw = JSON.parse(fs.readFileSync(configPath, "utf8"))
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      return { ...DEFAULT_CONFIG }
+    }
+  } catch {
+    return { ...DEFAULT_CONFIG }
+  }
+
+  return pickKnownKeys(raw)
+}
+
+export function saveConfig(config: AgentikitConfig, stashDir?: string): void {
+  const dir = stashDir ?? resolveStashDir()
+  const configPath = getConfigPath(dir)
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8")
+}
+
+export function updateConfig(
+  partial: Partial<AgentikitConfig>,
+  stashDir?: string,
+): AgentikitConfig {
+  const dir = stashDir ?? resolveStashDir()
+  const current = loadConfig(dir)
+  const merged: AgentikitConfig = { ...current, ...partial }
+  saveConfig(merged, dir)
+  return merged
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function pickKnownKeys(raw: Record<string, unknown>): AgentikitConfig {
+  const config: AgentikitConfig = { ...DEFAULT_CONFIG }
+
+  if (typeof raw.semanticSearch === "boolean") {
+    config.semanticSearch = raw.semanticSearch
+  }
+
+  if (Array.isArray(raw.additionalStashDirs)) {
+    config.additionalStashDirs = raw.additionalStashDirs.filter(
+      (d): d is string => typeof d === "string",
+    )
+  }
+
+  const embedding = parseConnectionConfig(raw.embedding)
+  if (embedding) config.embedding = embedding
+
+  const llm = parseConnectionConfig(raw.llm)
+  if (llm) config.llm = llm
+
+  const registry = parseRegistryConfig(raw.registry)
+  if (registry) config.registry = registry
+
+  return config
+}
+
+function parseConnectionConfig(
+  value: unknown,
+): EmbeddingConnectionConfig | LlmConnectionConfig | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined
+  const obj = value as Record<string, unknown>
+  if (typeof obj.endpoint !== "string" || !obj.endpoint) return undefined
+  if (typeof obj.model !== "string" || !obj.model) return undefined
+  const result: { endpoint: string; model: string; apiKey?: string } = {
+    endpoint: obj.endpoint,
+    model: obj.model,
+  }
+  if (typeof obj.apiKey === "string" && obj.apiKey) {
+    result.apiKey = obj.apiKey
+  }
+  return result
+}
+
+function parseRegistryConfig(value: unknown): RegistryConfig | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined
+  const obj = value as Record<string, unknown>
+  if (!Array.isArray(obj.installed)) return undefined
+
+  const installed = obj.installed
+    .map((entry) => parseRegistryInstalledEntry(entry))
+    .filter((entry): entry is RegistryInstalledEntry => entry !== undefined)
+
+  return { installed }
+}
+
+function parseRegistryInstalledEntry(value: unknown): RegistryInstalledEntry | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined
+  const obj = value as Record<string, unknown>
+
+  const id = asNonEmptyString(obj.id)
+  const source = asRegistrySource(obj.source)
+  const ref = asNonEmptyString(obj.ref)
+  const artifactUrl = asNonEmptyString(obj.artifactUrl)
+  const stashRoot = asNonEmptyString(obj.stashRoot)
+  const cacheDir = asNonEmptyString(obj.cacheDir)
+  const installedAt = asNonEmptyString(obj.installedAt)
+  if (!id || !source || !ref || !artifactUrl || !stashRoot || !cacheDir || !installedAt) return undefined
+
+  const entry: RegistryInstalledEntry = {
+    id,
+    source,
+    ref,
+    artifactUrl,
+    stashRoot,
+    cacheDir,
+    installedAt,
+  }
+  const resolvedVersion = asNonEmptyString(obj.resolvedVersion)
+  if (resolvedVersion) entry.resolvedVersion = resolvedVersion
+  const resolvedRevision = asNonEmptyString(obj.resolvedRevision)
+  if (resolvedRevision) entry.resolvedRevision = resolvedRevision
+  return entry
+}
+
+function asNonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value ? value : undefined
+}
+
+function asRegistrySource(value: unknown): RegistrySource | undefined {
+  return value === "npm" || value === "github" ? value : undefined
+}

package/src/embedder.ts

@@ -0,0 +1,117 @@
+import type { EmbeddingConnectionConfig } from "./config"
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export type EmbeddingVector = number[]
+
+// ── Singleton local embedder ────────────────────────────────────────────────
+
+let localEmbedder: any
+
+async function getLocalEmbedder(): Promise<any> {
+  if (!localEmbedder) {
+    let pipeline: any
+    try {
+      const mod = await import("@xenova/transformers")
+      pipeline = mod.pipeline
+    } 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")
+  }
+  return localEmbedder
+}
+
+async function embedLocal(text: string): Promise<EmbeddingVector> {
+  const model = await getLocalEmbedder()
+  const result = await model(text, { pooling: "mean", normalize: true })
+  return Array.from(result.data) as number[]
+}
+
+// ── OpenAI-compatible remote embedder ───────────────────────────────────────
+
+async function embedRemote(
+  text: string,
+  config: EmbeddingConnectionConfig,
+): Promise<EmbeddingVector> {
+  const headers: Record<string, string> = { "Content-Type": "application/json" }
+  if (config.apiKey) {
+    headers["Authorization"] = `Bearer ${config.apiKey}`
+  }
+
+  const response = await fetch(config.endpoint, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      input: text,
+      model: config.model,
+    }),
+  })
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "")
+    throw new Error(`Embedding request failed (${response.status}): ${body}`)
+  }
+
+  const json = (await response.json()) as {
+    data: Array<{ embedding: number[] }>
+  }
+
+  if (!json.data?.[0]?.embedding) {
+    throw new Error("Unexpected embedding response format: missing data[0].embedding")
+  }
+
+  return json.data[0].embedding
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Generate an embedding for the given text.
+ * If embeddingConfig is provided, uses the configured OpenAI-compatible endpoint.
+ * Otherwise falls back to local @xenova/transformers.
+ */
+export async function embed(
+  text: string,
+  embeddingConfig?: EmbeddingConnectionConfig,
+): Promise<EmbeddingVector> {
+  if (embeddingConfig) {
+    return embedRemote(text, embeddingConfig)
+  }
+  return embedLocal(text)
+}
+
+// ── Similarity ──────────────────────────────────────────────────────────────
+
+export function cosineSimilarity(a: EmbeddingVector, b: EmbeddingVector): number {
+  const len = Math.min(a.length, b.length)
+  if (len === 0) return 0
+  let dot = 0
+  for (let i = 0; i < len; i++) {
+    dot += a[i] * b[i]
+  }
+  return dot
+}
+
+// ── Availability check ──────────────────────────────────────────────────────
+
+export async function isEmbeddingAvailable(
+  embeddingConfig?: EmbeddingConnectionConfig,
+): Promise<boolean> {
+  if (embeddingConfig) {
+    try {
+      await embedRemote("test", embeddingConfig)
+      return true
+    } catch {
+      return false
+    }
+  }
+  try {
+    await getLocalEmbedder()
+    return true
+  } catch {
+    return false
+  }
+}

package/src/frontmatter.ts

@@ -0,0 +1,95 @@
+/**
+ * Shared frontmatter parsing utilities.
+ *
+ * Provides a single, canonical YAML-subset frontmatter parser used by both
+ * the stash open logic and the metadata generator.
+ */
+
+/**
+ * Parse YAML-subset frontmatter from a Markdown (or similar) string.
+ *
+ * Returns the parsed key-value data and the remaining body content.
+ */
+export function parseFrontmatter(raw: string): {
+  data: Record<string, unknown>
+  content: string
+  frontmatter: string | null
+  bodyStartLine: number
+} {
+  const parsedBlock = parseFrontmatterBlock(raw)
+  if (!parsedBlock) {
+    return { data: {}, content: raw, frontmatter: null, bodyStartLine: 1 }
+  }
+
+  const data: Record<string, unknown> = {}
+  let currentKey: string | null = null
+  let nested: Record<string, unknown> | null = null
+
+  for (const line of parsedBlock.frontmatter.split(/\r?\n/)) {
+    const indented = line.match(/^  (\w[\w-]*):\s*(.+)$/)
+    if (indented && currentKey && nested) {
+      nested[indented[1]] = parseYamlScalar(indented[2].trim())
+      continue
+    }
+
+    const top = line.match(/^(\w[\w-]*):\s*(.*)$/)
+    if (!top) {
+      continue
+    }
+
+    currentKey = top[1]
+    const value = top[2].trim()
+    if (value === "") {
+      nested = {}
+      data[currentKey] = nested
+    } else {
+      nested = null
+      data[currentKey] = parseYamlScalar(value)
+    }
+  }
+  return {
+    data,
+    content: parsedBlock.content,
+    frontmatter: parsedBlock.frontmatter,
+    bodyStartLine: parsedBlock.bodyStartLine,
+  }
+}
+
+export function parseFrontmatterBlock(
+  raw: string,
+): { frontmatter: string; content: string; bodyStartLine: number } | null {
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/)
+  if (!match) return null
+  return {
+    frontmatter: match[1],
+    content: match[2],
+    bodyStartLine: countLines(raw.slice(0, match[0].length - match[2].length)) + 1,
+  }
+}
+
+function countLines(text: string): number {
+  if (text.length === 0) return 0
+  return text.split(/\r?\n/).length - 1
+}
+
+/**
+ * Parse a simple YAML scalar value (string, boolean, or number).
+ */
+export function parseYamlScalar(value: string): unknown {
+  if (value === "") return ""
+  if (value === "true") return true
+  if (value === "false") return false
+  const asNumber = Number(value)
+  if (!Number.isNaN(asNumber)) return asNumber
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    return value.slice(1, -1)
+  }
+  return value
+}
+
+/**
+ * Coerce an unknown value to a trimmed string, or return undefined if empty/non-string.
+ */
+export function toStringOrUndefined(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined
+}