agentikit 0.0.9 → 0.0.13

package/src/stash-show.ts

@@ -1,24 +1,17 @@
 import fs from "node:fs"
-import path from "node:path"
-import { parseFrontmatter, toStringOrUndefined } from "./frontmatter"
-import { resolveStashDir } from "./common"
-import { parseOpenRef } from "./stash-ref"
+import { parseAssetRef } from "./stash-ref"
+import { resolveSourcesForOrigin } from "./origin-resolve"
 import { resolveAssetPath } from "./stash-resolve"
 import type { KnowledgeView, ShowResponse } from "./stash-types"
-import { parseMarkdownToc, extractSection, extractLineRange, extractFrontmatterOnly, formatToc } from "./markdown"
-import { buildToolInfo } from "./tool-runner"
-import { loadConfig } from "./config"
+import { getHandler } from "./asset-type-handler"
+import { resolveStashSources, findSourceForPath } from "./stash-source"
 
-export function agentikitShow(input: { ref: string; view?: KnowledgeView }): ShowResponse {
-  const parsed = parseOpenRef(input.ref)
-  const stashDir = resolveStashDir()
-  const config = loadConfig(stashDir)
-  const allStashDirs = [
-    stashDir,
-    ...config.additionalStashDirs.filter((d) => {
-      try { return fs.statSync(d).isDirectory() } catch { return false }
-    }),
-  ]
+export async function agentikitShow(input: { ref: string; view?: KnowledgeView }): Promise<ShowResponse> {
+  const parsed = parseAssetRef(input.ref)
+  const allSources = resolveStashSources()
+  const searchSources = resolveSourcesForOrigin(parsed.origin, allSources)
+
+  const allStashDirs = searchSources.map((s) => s.path)
 
   let assetPath: string | undefined
   let lastError: Error | undefined
@@ -30,83 +23,33 @@ export function agentikitShow(input: { ref: string; view?: KnowledgeView }): Sho
       lastError = err instanceof Error ? err : new Error(String(err))
     }
   }
+
+  if (!assetPath && parsed.origin && searchSources.length === 0) {
+    const installCmd = `akm add ${parsed.origin}`
+    throw new Error(
+      `Stash asset not found for ref: ${parsed.type}:${parsed.name}. ` +
+      `Kit "${parsed.origin}" is not installed. Run: ${installCmd}`
+    )
+  }
+
   if (!assetPath) {
     throw lastError ?? new Error(`Stash asset not found for ref: ${parsed.type}:${parsed.name}`)
   }
   const content = fs.readFileSync(assetPath, "utf8")
 
-  switch (parsed.type) {
-    case "skill":
-      return {
-        type: "skill",
-        name: parsed.name,
-        path: assetPath,
-        content,
-      }
-    case "command": {
-      const parsedMd = parseFrontmatter(content)
-      return {
-        type: "command",
-        name: parsed.name,
-        path: assetPath,
-        description: toStringOrUndefined(parsedMd.data.description),
-        template: parsedMd.content,
-      }
-    }
-    case "agent": {
-      const parsedMd = parseFrontmatter(content)
-      return {
-        type: "agent",
-        name: parsed.name,
-        path: assetPath,
-        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,
-      }
-    }
-    case "tool": {
-      const assetStashDir = allStashDirs.find((d) => path.resolve(assetPath!).startsWith(path.resolve(d) + path.sep)) ?? stashDir
-      const toolInfo = buildToolInfo(assetStashDir, assetPath)
-      return {
-        type: "tool",
-        name: parsed.name,
-        path: assetPath,
-        runCmd: toolInfo.runCmd,
-        kind: toolInfo.kind,
-      }
-    }
-    case "knowledge": {
-      const v = input.view ?? { mode: "full" }
-      switch (v.mode) {
-        case "toc": {
-          const toc = parseMarkdownToc(content)
-          return { type: "knowledge", name: parsed.name, path: assetPath, content: formatToc(toc) }
-        }
-        case "frontmatter": {
-          const fm = extractFrontmatterOnly(content)
-          return { type: "knowledge", name: parsed.name, path: assetPath, content: fm ?? "(no frontmatter)" }
-        }
-        case "section": {
-          const section = extractSection(content, v.heading)
-          if (!section) {
-            return {
-              type: "knowledge",
-              name: parsed.name,
-              path: assetPath,
-              content: `Section "${v.heading}" not found in ${parsed.name}. Try --view toc to discover available headings.`,
-            }
-          }
-          return { type: "knowledge", name: parsed.name, path: assetPath, content: section.content }
-        }
-        case "lines": {
-          return { type: "knowledge", name: parsed.name, path: assetPath, content: extractLineRange(content, v.start, v.end) }
-        }
-        default: {
-          return { type: "knowledge", name: parsed.name, path: assetPath, content }
-        }
-      }
-    }
+  const source = findSourceForPath(assetPath, allSources)
+  const handler = getHandler(parsed.type)
+  const response = handler.buildShowResponse({
+    name: parsed.name,
+    path: assetPath,
+    content,
+    view: input.view,
+    stashDirs: allStashDirs,
+  })
+
+  return {
+    ...response,
+    registryId: source?.registryId,
+    editable: source?.writable ?? false,
   }
 }

package/src/stash-source.ts

@@ -0,0 +1,103 @@
+import fs from "node:fs"
+import path from "node:path"
+import { resolveStashDir } from "./common"
+import { loadConfig } from "./config"
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export type StashSourceKind = "working" | "mounted" | "installed"
+
+export interface StashSource {
+  kind: StashSourceKind
+  path: string
+  /** For installed sources, the registry entry id */
+  registryId?: string
+  /** Whether this source is writable (only working stash) */
+  writable: boolean
+}
+
+// ── Resolution ──────────────────────────────────────────────────────────────
+
+/**
+ * Build the ordered list of stash sources:
+ *   1. Working stash (writable)
+ *   2. Mounted stash dirs (read-only, user-configured)
+ *   3. Installed stash dirs (read-only, derived from registry.installed)
+ */
+export function resolveStashSources(overrideStashDir?: string): StashSource[] {
+  const stashDir = overrideStashDir ?? resolveStashDir()
+  const config = loadConfig()
+
+  const sources: StashSource[] = [
+    { kind: "working", path: stashDir, writable: true },
+  ]
+
+  for (const dir of config.mountedStashDirs) {
+    if (isSuspiciousStashRoot(dir)) {
+      console.warn(`Warning: stash root "${dir}" appears to be a system directory. This may be unintentional.`)
+    }
+    if (isValidDirectory(dir)) {
+      sources.push({ kind: "mounted", path: dir, writable: false })
+    }
+  }
+
+  for (const entry of config.registry?.installed ?? []) {
+    if (isSuspiciousStashRoot(entry.stashRoot)) {
+      console.warn(`Warning: stash root "${entry.stashRoot}" appears to be a system directory. This may be unintentional.`)
+    }
+    if (isValidDirectory(entry.stashRoot)) {
+      sources.push({
+        kind: "installed",
+        path: entry.stashRoot,
+        registryId: entry.id,
+        writable: false,
+      })
+    }
+  }
+
+  return sources
+}
+
+/**
+ * Convenience: returns just the directory paths, preserving priority order.
+ */
+export function resolveAllStashDirs(overrideStashDir?: string): string[] {
+  return resolveStashSources(overrideStashDir).map((s) => s.path)
+}
+
+/**
+ * Find which source a file path belongs to.
+ */
+export function findSourceForPath(filePath: string, sources: StashSource[]): StashSource | undefined {
+  const resolved = path.resolve(filePath)
+  for (const source of sources) {
+    if (resolved.startsWith(path.resolve(source.path) + path.sep)) return source
+  }
+  return undefined
+}
+
+// ── Validation ──────────────────────────────────────────────────────────────
+
+const SUSPICIOUS_ROOTS = new Set(['/', '/etc', '/bin', '/sbin', '/usr', '/var', '/tmp', '/dev', '/proc', '/sys'])
+
+function isSuspiciousStashRoot(dir: string): boolean {
+  const resolved = path.resolve(dir)
+  const normalized = process.platform === 'win32' ? resolved.toLowerCase() : resolved
+  if (SUSPICIOUS_ROOTS.has(normalized)) return true
+  if (process.platform === 'win32') {
+    // Check for Windows system directories
+    const winDir = (process.env.SystemRoot || 'C:\\Windows').toLowerCase()
+    if (normalized === winDir || normalized.startsWith(winDir + path.sep)) return true
+  }
+  return false
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function isValidDirectory(dir: string): boolean {
+  try {
+    return fs.statSync(dir).isDirectory()
+  } catch {
+    return false
+  }
+}

package/src/stash-types.ts

@@ -12,6 +12,10 @@ export interface LocalSearchHit {
   name: string
   path: string
   openRef: string
+  /** For installed sources, the registry id */
+  registryId?: string
+  /** Whether this asset is editable (only true for working stash) */
+  editable?: boolean
   description?: string
   tags?: string[]
   score?: number
@@ -41,6 +45,8 @@ export interface RegistrySearchResultHit {
   metadata?: Record<string, string>
   installRef: string
   installCmd: string
+  /** Whether this entry was manually reviewed and approved */
+  curated?: boolean
 }
 
 export type SearchHit = LocalSearchHit | RegistrySearchResultHit
@@ -72,7 +78,7 @@ export interface AddResponse {
     installedAt: string
   }
   config: {
-    additionalStashDirs: string[]
+    mountedStashDirs: string[]
     installedRegistryCount: number
   }
   index: {
@@ -129,7 +135,7 @@ export interface RemoveResponse {
     stashRoot: string
   }
   config: {
-    additionalStashDirs: string[]
+    mountedStashDirs: string[]
     installedRegistryCount: number
   }
   index: {
@@ -154,7 +160,7 @@ export interface ReinstallResponse {
   all: boolean
   processed: ReinstallResultItem[]
   config: {
-    additionalStashDirs: string[]
+    mountedStashDirs: string[]
     installedRegistryCount: number
   }
   index: {
@@ -188,7 +194,7 @@ export interface UpdateResponse {
   all: boolean
   processed: UpdateResultItem[]
   config: {
-    additionalStashDirs: string[]
+    mountedStashDirs: string[]
     installedRegistryCount: number
   }
   index: {
@@ -211,6 +217,10 @@ export interface ShowResponse {
   modelHint?: unknown
   runCmd?: string
   kind?: ToolKind
+  /** For installed sources, the registry id */
+  registryId?: string
+  /** Whether this asset is editable (only true for working stash) */
+  editable?: boolean
 }
 
 export type KnowledgeView =

package/src/stash.ts

@@ -3,11 +3,17 @@ export { resolveStashDir } from "./common"
 export { agentikitInit } from "./init"
 export type { InitResponse } from "./init"
 export type { ToolKind } from "./tool-runner"
+export type { AssetTypeHandler, ShowInput } from "./asset-type-handler"
+export { registerAssetType, getHandler, getAllHandlers, getRegisteredTypeNames } from "./asset-type-handler"
 
 export { agentikitSearch } from "./stash-search"
 export { agentikitShow } from "./stash-show"
 export { agentikitAdd } from "./stash-add"
+export { agentikitClone } from "./stash-clone"
+
 export { agentikitList, agentikitRemove, agentikitReinstall, agentikitUpdate } from "./stash-registry"
+export { resolveStashSources, resolveAllStashDirs, findSourceForPath } from "./stash-source"
+export type { StashSource, StashSourceKind } from "./stash-source"
 
 export type {
   AddResponse,
@@ -29,3 +35,5 @@ export type {
   ReinstallResultItem,
   UpdateResultItem,
 } from "./stash-types"
+
+export type { CloneOptions, CloneResponse } from "./stash-clone"

package/src/tool-runner.ts

@@ -34,7 +34,7 @@ export interface ToolInfo {
  *
  * For `.ts` / `.js` files, looks up the nearest `package.json` so that
  * `bun install` can be run in the correct working directory when the
- * `AGENTIKIT_BUN_INSTALL` env flag is set.
+ * `AKM_BUN_INSTALL` env flag is set.
  */
 export function buildToolInfo(stashDir: string, filePath: string): ToolInfo {
   const ext = path.extname(filePath).toLowerCase()
@@ -67,8 +67,17 @@ export function buildToolInfo(stashDir: string, filePath: string): ToolInfo {
     throw new Error(`Unsupported tool extension: ${ext}`)
   }
 
-  const toolsRoot = path.resolve(path.join(stashDir, "tools"))
-  const pkgDir = findNearestPackageDir(path.dirname(filePath), toolsRoot)
+  // Determine the type root by checking which subdirectory contains the file
+  const resolvedFile = path.resolve(filePath)
+  let typeRoot = path.resolve(path.join(stashDir, "tools"))
+  for (const subdir of ["tools", "scripts"]) {
+    const candidate = path.resolve(path.join(stashDir, subdir))
+    if (resolvedFile.startsWith(candidate + path.sep)) {
+      typeRoot = candidate
+      break
+    }
+  }
+  const pkgDir = findNearestPackageDir(path.dirname(filePath), typeRoot)
   if (!pkgDir) {
     return {
       runCmd: `bun ${shellQuote(filePath)}`,
@@ -76,7 +85,7 @@ export function buildToolInfo(stashDir: string, filePath: string): ToolInfo {
       execute: { command: "bun", args: [filePath] },
     }
   }
-  const installFlag = process.env.AGENTIKIT_BUN_INSTALL
+  const installFlag = process.env.AKM_BUN_INSTALL
   const shouldInstall = installFlag === "1" || installFlag === "true" || installFlag === "yes"
 
   const quotedPkgDir = shellQuote(pkgDir)
@@ -101,7 +110,11 @@ export function shellQuote(input: string): string {
     throw new Error("Unsupported control characters in stash path.")
   }
   if (IS_WINDOWS) {
-    return `"${input.replace(/"/g, '""')}"`
+    const escaped = input
+      .replace(/%/g, "%%")
+      .replace(/([\\^|&<>])/g, "^$1")
+      .replace(/"/g, '""')
+    return `"${escaped}"`
   }
   const escaped = input
     .replace(/\\/g, "\\\\")

package/dist/src/similarity.d.ts

@@ -1,34 +0,0 @@
-import type { StashEntry } from "./metadata";
-export interface ScoredEntry {
-    id: string;
-    text: string;
-    entry: StashEntry;
-    path: string;
-}
-export interface ScoredResult {
-    entry: StashEntry;
-    path: string;
-    score: number;
-}
-export interface SearchAdapter {
-    buildIndex(entries: ScoredEntry[]): void;
-    search(query: string, limit: number, typeFilter?: string): ScoredResult[];
-}
-export interface SerializedTfIdf {
-    idf: Record<string, number>;
-    docs: Array<{
-        id: string;
-        termFreqs: Record<string, number>;
-        magnitude: number;
-    }>;
-}
-export declare class TfIdfAdapter implements SearchAdapter {
-    private documents;
-    private idf;
-    private entries;
-    buildIndex(entries: ScoredEntry[]): void;
-    search(query: string, limit: number, typeFilter?: string): ScoredResult[];
-    serialize(): SerializedTfIdf;
-    static deserialize(data: SerializedTfIdf, entries: ScoredEntry[]): TfIdfAdapter;
-    private substringFallback;
-}

package/dist/src/similarity.js

@@ -1,211 +0,0 @@
-export class TfIdfAdapter {
-    documents = [];
-    idf = new Map();
-    entries = [];
-    buildIndex(entries) {
-        this.entries = entries;
-        const docCount = entries.length;
-        if (docCount === 0)
-            return;
-        // Compute term frequencies per document
-        const docFreqs = new Map();
-        this.documents = entries.map((entry) => {
-            const tokens = tokenize(entry.text);
-            const termFreqs = new Map();
-            for (const token of tokens) {
-                termFreqs.set(token, (termFreqs.get(token) || 0) + 1);
-            }
-            // Track document frequency for IDF
-            for (const term of termFreqs.keys()) {
-                docFreqs.set(term, (docFreqs.get(term) || 0) + 1);
-            }
-            return { entry, termFreqs, magnitude: 0 };
-        });
-        // Compute IDF: log(N / df)
-        this.idf = new Map();
-        for (const [term, df] of docFreqs) {
-            this.idf.set(term, Math.log(docCount / df));
-        }
-        // Compute document magnitudes for cosine similarity
-        for (const doc of this.documents) {
-            let sumSq = 0;
-            for (const [term, tf] of doc.termFreqs) {
-                const idf = this.idf.get(term) || 0;
-                const tfidf = tf * idf;
-                sumSq += tfidf * tfidf;
-            }
-            doc.magnitude = Math.sqrt(sumSq);
-        }
-    }
-    search(query, limit, typeFilter) {
-        if (this.documents.length === 0)
-            return [];
-        const queryTokens = tokenize(query.toLowerCase());
-        if (queryTokens.length === 0) {
-            // Empty query: return all, sorted by type
-            return this.documents
-                .filter((d) => !typeFilter || typeFilter === "any" || d.entry.entry.type === typeFilter)
-                .slice(0, limit)
-                .map((d) => ({
-                entry: d.entry.entry,
-                path: d.entry.path,
-                score: 1,
-            }));
-        }
-        // Build query TF-IDF vector
-        const queryTermFreqs = new Map();
-        for (const token of queryTokens) {
-            queryTermFreqs.set(token, (queryTermFreqs.get(token) || 0) + 1);
-        }
-        let queryMagnitude = 0;
-        const queryVector = new Map();
-        for (const [term, tf] of queryTermFreqs) {
-            const idf = this.idf.get(term) || 0;
-            const tfidf = tf * idf;
-            queryVector.set(term, tfidf);
-            queryMagnitude += tfidf * tfidf;
-        }
-        queryMagnitude = Math.sqrt(queryMagnitude);
-        if (queryMagnitude === 0) {
-            // All query terms are unknown — fallback to substring match
-            return this.substringFallback(query, limit, typeFilter);
-        }
-        const results = [];
-        const querySet = new Set(queryTokens);
-        for (const doc of this.documents) {
-            if (typeFilter && typeFilter !== "any" && doc.entry.entry.type !== typeFilter)
-                continue;
-            // Cosine similarity
-            let dotProduct = 0;
-            for (const [term, queryTfidf] of queryVector) {
-                const docTf = doc.termFreqs.get(term) || 0;
-                if (docTf === 0)
-                    continue;
-                const docIdf = this.idf.get(term) || 0;
-                dotProduct += queryTfidf * (docTf * docIdf);
-            }
-            let score = doc.magnitude > 0 && queryMagnitude > 0
-                ? dotProduct / (doc.magnitude * queryMagnitude)
-                : 0;
-            // Boost: tag exact match
-            const tags = doc.entry.entry.tags || [];
-            for (const tag of tags) {
-                if (querySet.has(tag.toLowerCase())) {
-                    score += 0.15;
-                }
-            }
-            // Boost: intent phrase contains query token
-            const intents = doc.entry.entry.intents || [];
-            for (const intent of intents) {
-                const intentLower = intent.toLowerCase();
-                for (const token of queryTokens) {
-                    if (intentLower.includes(token)) {
-                        score += 0.12;
-                        break; // one boost per intent phrase
-                    }
-                }
-            }
-            // Boost: name contains query token
-            const nameLower = doc.entry.entry.name.toLowerCase().replace(/[-_]/g, " ");
-            for (const token of queryTokens) {
-                if (nameLower.includes(token)) {
-                    score += 0.1;
-                    break;
-                }
-            }
-            if (score > 0) {
-                results.push({
-                    entry: doc.entry.entry,
-                    path: doc.entry.path,
-                    score: Math.round(score * 1000) / 1000,
-                });
-            }
-        }
-        results.sort((a, b) => b.score - a.score);
-        return results.slice(0, limit);
-    }
-    serialize() {
-        const idf = {};
-        for (const [term, val] of this.idf) {
-            idf[term] = val;
-        }
-        const docs = this.documents.map((d) => {
-            const termFreqs = {};
-            for (const [term, tf] of d.termFreqs) {
-                termFreqs[term] = tf;
-            }
-            return { id: d.entry.id, termFreqs, magnitude: d.magnitude };
-        });
-        return { idf, docs };
-    }
-    static deserialize(data, entries) {
-        const adapter = new TfIdfAdapter();
-        adapter.entries = entries;
-        adapter.idf = new Map(Object.entries(data.idf));
-        const entryMap = new Map(entries.map((e) => [e.id, e]));
-        adapter.documents = data.docs
-            .map((d) => {
-            const entry = entryMap.get(d.id);
-            if (!entry)
-                return null;
-            return {
-                entry,
-                termFreqs: new Map(Object.entries(d.termFreqs)),
-                magnitude: d.magnitude,
-            };
-        })
-            .filter((d) => d !== null);
-        return adapter;
-    }
-    substringFallback(query, limit, typeFilter) {
-        const q = query.toLowerCase();
-        const tokens = tokenize(q);
-        return this.documents
-            .map((d) => {
-            if (typeFilter && typeFilter !== "any" && d.entry.entry.type !== typeFilter)
-                return null;
-            // Check if any query token matches the document text or name
-            const text = d.entry.text;
-            const name = d.entry.entry.name.toLowerCase();
-            let matchCount = 0;
-            for (const token of tokens) {
-                if (text.includes(token) || name.includes(token))
-                    matchCount++;
-            }
-            // Also check full substring match
-            if (text.includes(q) || name.includes(q))
-                matchCount = Math.max(matchCount, tokens.length);
-            if (matchCount === 0)
-                return null;
-            return {
-                entry: d.entry.entry,
-                path: d.entry.path,
-                score: Math.round((matchCount / Math.max(tokens.length, 1)) * 500) / 1000,
-            };
-        })
-            .filter((d) => d !== null)
-            .sort((a, b) => b.score - a.score)
-            .slice(0, limit);
-    }
-}
-// ── Tokenization ────────────────────────────────────────────────────────────
-const STOP_WORDS = new Set([
-    "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
-    "have", "has", "had", "do", "does", "did", "will", "would", "could",
-    "should", "may", "might", "shall", "can", "need", "dare", "ought",
-    "to", "of", "in", "for", "on", "with", "at", "by", "from", "as",
-    "into", "through", "during", "before", "after", "above", "below",
-    "and", "but", "or", "nor", "not", "so", "yet", "both", "either",
-    "neither", "each", "every", "all", "any", "few", "more", "most",
-    "other", "some", "such", "no", "only", "own", "same", "than",
-    "too", "very", "just", "because", "if", "when", "where", "how",
-    "what", "which", "who", "whom", "this", "that", "these", "those",
-    "it", "its",
-]);
-function tokenize(text) {
-    return text
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, " ")
-        .split(/\s+/)
-        .filter((t) => t.length > 1 && !STOP_WORDS.has(t));
-}