agentikit 0.0.9 → 0.0.13

package/dist/src/indexer.js

@@ -3,185 +3,194 @@ import path from "node:path";
 import { resolveStashDir } from "./common";
 import { ASSET_TYPES, TYPE_DIRS, deriveCanonicalAssetName } from "./asset-spec";
 import { loadStashFile, writeStashFile, generateMetadata, } from "./metadata";
-import { TfIdfAdapter } from "./similarity";
 import { walkStash } from "./walker";
-// ── Constants ───────────────────────────────────────────────────────────────
-const INDEX_VERSION = 4;
-// ── Index Path ──────────────────────────────────────────────────────────────
-export function getIndexPath() {
-    const cacheDir = process.env.XDG_CACHE_HOME
-        || path.join(process.env.HOME || process.env.USERPROFILE || "", ".cache");
-    return path.join(cacheDir, "agentikit", "index.json");
-}
-export function loadSearchIndex() {
-    const indexPath = getIndexPath();
-    if (!fs.existsSync(indexPath))
-        return null;
-    try {
-        const raw = JSON.parse(fs.readFileSync(indexPath, "utf8"));
-        if (raw?.version !== INDEX_VERSION)
-            return null;
-        return raw;
-    }
-    catch {
-        return null;
-    }
-}
+import { openDatabase, closeDatabase, getDbPath, getMeta, setMeta, upsertEntry, deleteEntriesByDir, rebuildFts, upsertEmbedding, getEntriesByDir, getEntryCount, isVecAvailable, DB_VERSION, } from "./db";
 // ── Indexer ──────────────────────────────────────────────────────────────────
 export async function agentikitIndex(options) {
     const stashDir = options?.stashDir || resolveStashDir();
-    // Load config to get additional stash dirs and semantic search setting
+    // Load config and resolve all stash sources
     const { loadConfig } = await import("./config.js");
-    const config = loadConfig(stashDir);
-    const allStashDirs = [stashDir];
-    for (const d of config.additionalStashDirs) {
-        try {
-            if (fs.statSync(d).isDirectory() && !allStashDirs.includes(path.resolve(d))) {
-                allStashDirs.push(path.resolve(d));
+    const config = loadConfig();
+    const { resolveAllStashDirs } = await import("./stash-source.js");
+    const allStashDirs = resolveAllStashDirs(stashDir);
+    const t0 = Date.now();
+    // Open database — pass embedding dimension from config if available
+    const dbPath = getDbPath();
+    const embeddingDim = config.embedding?.dimension;
+    const db = openDatabase(dbPath, embeddingDim ? { embeddingDim } : undefined);
+    try {
+        // Check if we should do incremental
+        const prevStashDir = getMeta(db, "stashDir");
+        const prevBuiltAt = getMeta(db, "builtAt");
+        const isIncremental = !options?.full && prevStashDir === stashDir && !!prevBuiltAt;
+        const builtAtMs = isIncremental ? new Date(prevBuiltAt).getTime() : 0;
+        if (options?.full || !isIncremental) {
+            // Wipe all entries for full rebuild or stashDir change
+            db.exec("DELETE FROM entries");
+            db.exec("DELETE FROM entries_fts");
+            if (isVecAvailable()) {
+                try {
+                    db.exec("DELETE FROM entries_vec");
+                }
+                catch { /* ignore */ }
             }
         }
-        catch { /* skip nonexistent dirs */ }
+        const tWalkStart = Date.now();
+        // Walk stash dirs and index entries
+        const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm } = indexEntries(db, allStashDirs, stashDir, isIncremental, builtAtMs);
+        // Enhance entries with LLM if configured
+        await enhanceDirsWithLlm(db, config, dirsNeedingLlm);
+        const tWalkEnd = Date.now();
+        // Rebuild FTS after all inserts
+        rebuildFts(db);
+        const tFtsEnd = Date.now();
+        // Generate embeddings if semantic search is enabled
+        const hasEmbeddings = await generateEmbeddingsForDb(db, config);
+        const tEmbedEnd = Date.now();
+        // Update metadata
+        setMeta(db, "version", String(DB_VERSION));
+        setMeta(db, "builtAt", new Date().toISOString());
+        setMeta(db, "stashDir", stashDir);
+        setMeta(db, "stashDirs", JSON.stringify(allStashDirs));
+        setMeta(db, "hasEmbeddings", hasEmbeddings ? "1" : "0");
+        const totalEntries = getEntryCount(db);
+        const tEnd = Date.now();
+        return {
+            stashDir,
+            totalEntries,
+            generatedMetadata: generatedCount,
+            indexPath: dbPath,
+            mode: isIncremental ? "incremental" : "full",
+            directoriesScanned: scannedDirs,
+            directoriesSkipped: skippedDirs,
+            timing: {
+                totalMs: tEnd - t0,
+                walkMs: tWalkEnd - tWalkStart,
+                embedMs: tEmbedEnd - tFtsEnd,
+                ftsMs: tFtsEnd - tWalkEnd,
+            },
+        };
     }
-    const t0 = Date.now();
-    const allEntries = [];
-    let generatedCount = 0;
+    finally {
+        closeDatabase(db);
+    }
+}
+// ── Extracted helpers for agentikitIndex ─────────────────────────────────────
+function indexEntries(db, allStashDirs, stashDir, isIncremental, builtAtMs) {
     let scannedDirs = 0;
     let skippedDirs = 0;
-    // Load previous index for incremental mode
-    const previousIndex = !options?.full ? loadSearchIndex() : null;
-    const isIncremental = previousIndex !== null && previousIndex.stashDir === stashDir;
-    const builtAtMs = isIncremental ? new Date(previousIndex.builtAt).getTime() : 0;
-    // Build lookup of previous entries by dirPath
-    const previousEntriesByDir = new Map();
-    if (isIncremental) {
-        for (const ie of previousIndex.entries) {
-            const list = previousEntriesByDir.get(ie.dirPath) || [];
-            list.push(ie);
-            previousEntriesByDir.set(ie.dirPath, list);
-        }
-    }
+    let generatedCount = 0;
     const seenPaths = new Set();
-    const tWalkStart = Date.now();
-    for (const currentStashDir of allStashDirs) {
-        for (const assetType of ASSET_TYPES) {
-            const typeRoot = path.join(currentStashDir, TYPE_DIRS[assetType]);
-            try {
-                if (!fs.statSync(typeRoot).isDirectory())
-                    continue;
-            }
-            catch {
-                continue;
-            }
-            // Group files by their immediate parent directory
-            const dirGroups = walkStash(typeRoot, assetType);
-            for (const { dirPath, files } of dirGroups) {
-                // Deduplicate by dirPath across stash dirs
-                if (seenPaths.has(path.resolve(dirPath)))
-                    continue;
-                seenPaths.add(path.resolve(dirPath));
-                // Incremental: skip directories that haven't changed
-                const prevEntries = previousEntriesByDir.get(dirPath);
-                if (isIncremental && prevEntries && !isDirStale(dirPath, files, prevEntries, builtAtMs)) {
-                    allEntries.push(...prevEntries);
-                    skippedDirs++;
+    const dirsNeedingLlm = [];
+    const insertTransaction = db.transaction(() => {
+        for (const currentStashDir of allStashDirs) {
+            for (const assetType of ASSET_TYPES) {
+                const typeRoot = path.join(currentStashDir, TYPE_DIRS[assetType]);
+                try {
+                    if (!fs.statSync(typeRoot).isDirectory())
+                        continue;
+                }
+                catch {
                     continue;
                 }
-                scannedDirs++;
-                // Try loading existing .stash.json
-                let stash = loadStashFile(dirPath);
-                if (stash) {
-                    const migration = migrateGeneratedSkillMetadata(stash, files, typeRoot);
-                    if (migration.changed) {
-                        stash = migration.stash;
-                        writeStashFile(dirPath, stash);
+                const dirGroups = walkStash(typeRoot, assetType);
+                for (const { dirPath, files } of dirGroups) {
+                    if (seenPaths.has(path.resolve(dirPath)))
+                        continue;
+                    seenPaths.add(path.resolve(dirPath));
+                    // Incremental: skip directories that haven't changed
+                    if (isIncremental) {
+                        const prevEntries = getEntriesByDir(db, dirPath);
+                        if (prevEntries.length > 0 && !isDirStale(dirPath, files, prevEntries, builtAtMs)) {
+                            skippedDirs++;
+                            continue;
+                        }
                     }
-                }
-                if (!stash) {
-                    // Generate metadata
-                    stash = generateMetadata(dirPath, assetType, files, typeRoot);
-                    // Enhance with LLM if configured
-                    if (config.llm && stash.entries.length > 0) {
-                        stash = await enhanceStashWithLlm(config.llm, stash, dirPath, files);
+                    scannedDirs++;
+                    // Delete old entries for this dir (will be re-inserted)
+                    deleteEntriesByDir(db, dirPath);
+                    // Try loading existing .stash.json (user metadata overrides)
+                    let stash = loadStashFile(dirPath);
+                    if (stash) {
+                        const migration = migrateGeneratedSkillMetadata(stash, files, typeRoot);
+                        if (migration.changed) {
+                            stash = migration.stash;
+                            writeStashFile(dirPath, stash);
+                        }
                     }
-                    if (stash.entries.length > 0) {
-                        writeStashFile(dirPath, stash);
-                        generatedCount += stash.entries.length;
+                    if (!stash) {
+                        // Generate metadata heuristically
+                        stash = generateMetadata(dirPath, assetType, files, typeRoot);
+                        if (stash.entries.length > 0) {
+                            writeStashFile(dirPath, stash);
+                            generatedCount += stash.entries.length;
+                        }
                     }
-                }
-                if (stash) {
-                    for (const entry of stash.entries) {
-                        const entryPath = entry.entry
-                            ? path.join(dirPath, entry.entry)
-                            : files[0] || dirPath;
-                        allEntries.push({ entry, path: entryPath, dirPath });
+                    if (stash) {
+                        for (const entry of stash.entries) {
+                            const entryPath = entry.entry
+                                ? path.join(dirPath, entry.entry)
+                                : files[0] || dirPath;
+                            const entryKey = `${currentStashDir}:${entry.type}:${entry.name}`;
+                            const searchText = buildSearchText(entry);
+                            upsertEntry(db, entryKey, dirPath, entryPath, currentStashDir, entry, searchText);
+                        }
+                        // Collect dirs needing LLM enhancement during the first walk
+                        if (stash.entries.some((e) => e.generated)) {
+                            dirsNeedingLlm.push({ dirPath, files, assetType, currentStashDir });
+                        }
                     }
                 }
             }
         }
-    }
-    const tWalkEnd = Date.now();
-    // Build TF-IDF index
-    const adapter = new TfIdfAdapter();
-    const scoredEntries = allEntries.map((ie) => ({
-        id: `${ie.entry.type}:${ie.entry.name}`,
-        text: buildSearchText(ie.entry),
-        entry: ie.entry,
-        path: ie.path,
-    }));
-    adapter.buildIndex(scoredEntries);
-    const tTfidfEnd = Date.now();
-    // Generate embeddings if semantic search is enabled
-    let hasEmbeddings = false;
-    if (config.semanticSearch) {
-        try {
-            const { embed } = await import("./embedder.js");
-            for (const ie of allEntries) {
-                if (!ie.embedding) {
-                    const text = buildSearchText(ie.entry);
-                    ie.embedding = await embed(text, config.embedding);
-                }
-            }
-            hasEmbeddings = true;
+    });
+    insertTransaction();
+    return { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm };
+}
+async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
+    if (!config.llm || dirsNeedingLlm.length === 0)
+        return;
+    for (const { dirPath, files, currentStashDir } of dirsNeedingLlm) {
+        let stash = loadStashFile(dirPath);
+        if (!stash)
+            continue;
+        stash = await enhanceStashWithLlm(config.llm, stash, dirPath, files);
+        writeStashFile(dirPath, stash);
+        // Re-upsert enhanced entries
+        for (const entry of stash.entries) {
+            const entryPath = entry.entry ? path.join(dirPath, entry.entry) : files[0] || dirPath;
+            const entryKey = `${currentStashDir}:${entry.type}:${entry.name}`;
+            const searchText = buildSearchText(entry);
+            upsertEntry(db, entryKey, dirPath, entryPath, currentStashDir, entry, searchText);
         }
-        catch {
-            // Embedding provider not available, continue without embeddings
+    }
+}
+async function generateEmbeddingsForDb(db, config) {
+    if (!config.semanticSearch || !isVecAvailable())
+        return false;
+    try {
+        const { embed } = await import("./embedder.js");
+        const allEntries = getAllEntriesForEmbedding(db);
+        for (const { id, searchText } of allEntries) {
+            const embedding = await embed(searchText, config.embedding);
+            upsertEmbedding(db, id, embedding);
         }
+        return true;
     }
-    const tEmbedEnd = Date.now();
-    // Persist index
-    const indexPath = getIndexPath();
-    const indexDir = path.dirname(indexPath);
-    if (!fs.existsSync(indexDir)) {
-        fs.mkdirSync(indexDir, { recursive: true });
+    catch (error) {
+        console.warn("Embedding generation failed, continuing without:", error instanceof Error ? error.message : String(error));
+        return false;
     }
-    const index = {
-        version: INDEX_VERSION,
-        builtAt: new Date().toISOString(),
-        stashDir,
-        stashDirs: allStashDirs,
-        entries: allEntries,
-        tfidf: adapter.serialize(),
-        hasEmbeddings,
-    };
-    fs.writeFileSync(indexPath, JSON.stringify(index) + "\n", "utf8");
-    const tEnd = Date.now();
-    return {
-        stashDir,
-        totalEntries: allEntries.length,
-        generatedMetadata: generatedCount,
-        indexPath,
-        mode: isIncremental ? "incremental" : "full",
-        directoriesScanned: scannedDirs,
-        directoriesSkipped: skippedDirs,
-        timing: {
-            totalMs: tEnd - t0,
-            walkMs: tWalkEnd - tWalkStart, // includes metadata generation (interleaved)
-            embedMs: tEmbedEnd - tTfidfEnd,
-            tfidfMs: tTfidfEnd - tWalkEnd,
-        },
-    };
 }
 // ── Helpers ─────────────────────────────────────────────────────────────────
+function getAllEntriesForEmbedding(db) {
+    return db
+        .prepare(`
+      SELECT e.id, e.search_text AS searchText FROM entries e
+      WHERE NOT EXISTS (SELECT 1 FROM entries_vec v WHERE v.id = e.id)
+    `)
+        .all();
+}
 function isDirStale(dirPath, currentFiles, previousEntries, builtAtMs) {
     // Check if file set changed (additions or deletions)
     const prevFileNames = new Set(previousEntries
@@ -244,7 +253,6 @@ async function enhanceStashWithLlm(llmConfig, stash, dirPath, files) {
     const enhanced = [];
     for (const entry of stash.entries) {
         try {
-            // Find the file matching this entry for content context
             const entryFile = entry.entry
                 ? files.find((f) => path.basename(f) === entry.entry) ?? files[0]
                 : files[0];
@@ -266,7 +274,6 @@ async function enhanceStashWithLlm(llmConfig, stash, dirPath, files) {
             enhanced.push(updated);
         }
         catch {
-            // LLM enhancement failed for this entry, keep original
             enhanced.push(entry);
         }
     }

package/dist/src/init.d.ts

@@ -1,7 +1,7 @@
 /**
  * Agentikit initialization logic.
  *
- * Creates the stash directory structure, sets the AGENTIKIT_STASH_DIR
+ * Creates the working stash directory structure, sets the AKM_STASH_DIR
  * environment variable, and ensures ripgrep is available.
  */
 export interface InitResponse {
@@ -16,4 +16,4 @@ export interface InitResponse {
         version: string;
     };
 }
-export declare function agentikitInit(): InitResponse;
+export declare function agentikitInit(): Promise<InitResponse>;

package/dist/src/init.js

@@ -1,7 +1,7 @@
 /**
  * Agentikit initialization logic.
  *
- * Creates the stash directory structure, sets the AGENTIKIT_STASH_DIR
+ * Creates the working stash directory structure, sets the AKM_STASH_DIR
  * environment variable, and ensures ripgrep is available.
  */
 import { spawnSync } from "node:child_process";
@@ -10,7 +10,7 @@ import path from "node:path";
 import { IS_WINDOWS, TYPE_DIRS } from "./common";
 import { ensureRg } from "./ripgrep-install";
 import { getConfigPath, saveConfig, DEFAULT_CONFIG } from "./config";
-export function agentikitInit() {
+export async function agentikitInit() {
     let stashDir;
     if (IS_WINDOWS) {
         const userProfile = process.env.USERPROFILE?.trim();
@@ -41,7 +41,7 @@ export function agentikitInit() {
     let envSet = false;
     let profileUpdated;
     if (IS_WINDOWS) {
-        const result = spawnSync("setx", ["AGENTIKIT_STASH_DIR", stashDir], {
+        const result = spawnSync("setx", ["AKM_STASH_DIR", stashDir], {
             encoding: "utf8",
             timeout: 10_000,
         });
@@ -60,20 +60,32 @@ export function agentikitInit() {
         else {
             profile = path.join(homeDir, ".profile");
         }
-        const exportLine = `export AGENTIKIT_STASH_DIR="${stashDir}"`;
+        const exportLine = `export AKM_STASH_DIR="${stashDir}"`;
         const existing = fs.existsSync(profile) ? fs.readFileSync(profile, "utf8") : "";
-        if (!existing.includes("AGENTIKIT_STASH_DIR")) {
-            fs.appendFileSync(profile, `\n# Agentikit stash directory\n${exportLine}\n`);
+        if (!existing.includes("AKM_STASH_DIR")) {
+            const updated = existing + `\n# Agentikit working stash directory\n${exportLine}\n`;
+            const tmpPath = profile + `.tmp.${process.pid}`;
+            try {
+                fs.writeFileSync(tmpPath, updated, "utf8");
+                fs.renameSync(tmpPath, profile);
+            }
+            catch (err) {
+                try {
+                    fs.unlinkSync(tmpPath);
+                }
+                catch { /* ignore */ }
+                throw err;
+            }
             envSet = true;
             profileUpdated = profile;
         }
     }
     // Create default config.json if it doesn't exist
-    const configPath = getConfigPath(stashDir);
+    const configPath = getConfigPath();
     if (!fs.existsSync(configPath)) {
-        saveConfig(DEFAULT_CONFIG, stashDir);
+        saveConfig(DEFAULT_CONFIG);
     }
-    process.env.AGENTIKIT_STASH_DIR = stashDir;
+    process.env.AKM_STASH_DIR = stashDir;
     // Ensure ripgrep is available (install to stash/bin if needed)
     let ripgrep;
     try {

package/dist/src/llm.js

@@ -1,16 +1,17 @@
+import { fetchWithTimeout } from "./common";
 async function chatCompletion(config, messages) {
     const headers = { "Content-Type": "application/json" };
     if (config.apiKey) {
         headers["Authorization"] = `Bearer ${config.apiKey}`;
     }
-    const response = await fetch(config.endpoint, {
+    const response = await fetchWithTimeout(config.endpoint, {
         method: "POST",
         headers,
         body: JSON.stringify({
             model: config.model,
             messages,
-            temperature: 0.3,
-            max_tokens: 512,
+            temperature: config.temperature ?? 0.3,
+            max_tokens: config.maxTokens ?? 512,
         }),
     });
     if (!response.ok) {

package/dist/src/metadata.d.ts

@@ -30,7 +30,6 @@ export declare function loadStashFile(dirPath: string): StashFile | null;
 export declare function writeStashFile(dirPath: string, stash: StashFile): void;
 export declare function validateStashEntry(entry: unknown): StashEntry | null;
 export declare function generateMetadata(dirPath: string, assetType: AgentikitAssetType, files: string[], typeRoot?: string): StashFile;
-export declare function generateIntents(description: string, tags: string[], name: string): string[];
 export declare function extractDescriptionFromComments(filePath: string): string | null;
 export declare function extractFrontmatterDescription(filePath: string): string | null;
 export declare function extractPackageMetadata(dirPath: string): {

package/dist/src/metadata.js

@@ -1,9 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import { isAssetType } from "./common";
-import { SCRIPT_EXTENSIONS, isRelevantAssetFile, deriveCanonicalAssetName } from "./asset-spec";
+import { isRelevantAssetFile, deriveCanonicalAssetName } from "./asset-spec";
 import { parseFrontmatter, toStringOrUndefined } from "./frontmatter";
-import { parseMarkdownToc } from "./markdown";
+import { tryGetHandler } from "./asset-type-handler";
 // ── Load / Write ────────────────────────────────────────────────────────────
 const STASH_FILENAME = ".stash.json";
 export function stashFilePath(dirPath) {
@@ -153,26 +153,10 @@ export function generateMetadata(dirPath, assetType, files, typeRoot = dirPath)
                 entry.confidence = 0.9;
             }
         }
-        // Knowledge entries: generate TOC from headings
-        if (assetType === "knowledge") {
-            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
-            }
-        }
-        // Priority 3: Code comments (for script files)
-        if (SCRIPT_EXTENSIONS.has(ext) && ext !== ".md") {
-            const commentDesc = extractDescriptionFromComments(file);
-            if (commentDesc && !entry.description) {
-                entry.description = commentDesc;
-                entry.source = "comments";
-                entry.confidence = 0.7;
-            }
+        // Type-specific metadata extraction (e.g. TOC for knowledge, comments for tools/scripts)
+        const handler = tryGetHandler(assetType);
+        if (handler?.extractTypeMetadata) {
+            handler.extractTypeMetadata(entry, file, ext);
         }
         // Priority 4: Filename heuristics (fallback)
         if (!entry.description) {
@@ -214,48 +198,6 @@ function buildAliases(name, tags) {
         aliases.add(tags.join(" "));
     return Array.from(aliases);
 }
-// ── Intent Generation ────────────────────────────────────────────────────────
-export function generateIntents(description, tags, name) {
-    const intents = new Set();
-    // Split name on separators to extract tokens and potential verb
-    const nameTokens = name
-        .replace(/[-_]+/g, " ")
-        .replace(/([a-z])([A-Z])/g, "$1 $2")
-        .toLowerCase()
-        .trim()
-        .split(/\s+/)
-        .filter((t) => t.length > 1);
-    // Intent from name as phrase (e.g. "summarize diff")
-    const namePhrase = nameTokens.join(" ");
-    if (namePhrase.length > 2)
-        intents.add(namePhrase);
-    // Intent from description (lowercased)
-    const desc = description.toLowerCase().trim();
-    if (desc.length > 2)
-        intents.add(desc);
-    // Combine first name token (potential verb) with tags
-    // e.g. name "summarize-diff", tags ["git"] → "summarize git diff"
-    if (nameTokens.length >= 1 && tags.length > 0) {
-        const verb = nameTokens[0];
-        const rest = nameTokens.slice(1).join(" ");
-        for (const tag of tags) {
-            const tagLower = tag.toLowerCase();
-            // verb + tag + rest (e.g. "summarize git diff")
-            const parts = [verb, tagLower, rest].filter((p) => p.length > 0);
-            const phrase = parts.join(" ");
-            if (phrase !== namePhrase && phrase.length > 2)
-                intents.add(phrase);
-        }
-    }
-    // Join tag pairs (e.g. ["git", "diff"] → "git diff")
-    if (tags.length >= 2) {
-        const tagPhrase = tags.map((t) => t.toLowerCase()).join(" ");
-        if (tagPhrase.length > 2)
-            intents.add(tagPhrase);
-    }
-    // Cap at 8 intents
-    return Array.from(intents).slice(0, 8);
-}
 export function extractDescriptionFromComments(filePath) {
     let content;
     try {

package/dist/src/origin-resolve.d.ts

@@ -0,0 +1,19 @@
+import type { StashSource } from "./stash-source";
+/**
+ * Given an origin string (from an AssetRef) and the full list of stash
+ * sources, return the subset of sources to search.
+ *
+ * Resolution order:
+ *   1. undefined   → all sources (working → mounted → installed)
+ *   2. "local"     → working stash only
+ *   3. exact match → installed source whose registryId matches verbatim
+ *   4. parsed match → parse origin as a registry ref, match by parsed ID
+ *   5. path match  → mounted source whose path matches
+ *   6. empty       → indicates a remote/uninstalled origin (caller decides)
+ */
+export declare function resolveSourcesForOrigin(origin: string | undefined, allSources: StashSource[]): StashSource[];
+/**
+ * Check whether an origin refers to something that could be fetched remotely
+ * (i.e. it looks like a registry ref but isn't installed locally).
+ */
+export declare function isRemoteOrigin(origin: string, allSources: StashSource[]): boolean;

package/dist/src/origin-resolve.js

@@ -0,0 +1,53 @@
+import path from "node:path";
+import { parseRegistryRef } from "./registry-resolve";
+/**
+ * Given an origin string (from an AssetRef) and the full list of stash
+ * sources, return the subset of sources to search.
+ *
+ * Resolution order:
+ *   1. undefined   → all sources (working → mounted → installed)
+ *   2. "local"     → working stash only
+ *   3. exact match → installed source whose registryId matches verbatim
+ *   4. parsed match → parse origin as a registry ref, match by parsed ID
+ *   5. path match  → mounted source whose path matches
+ *   6. empty       → indicates a remote/uninstalled origin (caller decides)
+ */
+export function resolveSourcesForOrigin(origin, allSources) {
+    if (!origin)
+        return allSources;
+    if (origin === "local") {
+        return allSources.filter((s) => s.kind === "working");
+    }
+    // Exact registryId match (e.g. origin is "npm:@scope/pkg")
+    const byExactId = allSources.filter((s) => s.kind === "installed" && s.registryId === origin);
+    if (byExactId.length > 0)
+        return byExactId;
+    // Parse origin as a registry ref and match by parsed ID.
+    // Allows shorthand: "owner/repo" matches "github:owner/repo",
+    // "@scope/pkg" matches "npm:@scope/pkg".
+    try {
+        const parsed = parseRegistryRef(origin);
+        const byParsedId = allSources.filter((s) => s.kind === "installed" && s.registryId === parsed.id);
+        if (byParsedId.length > 0)
+            return byParsedId;
+    }
+    catch {
+        // Not a valid registry ref — continue to path matching
+    }
+    // Mounted stash by resolved path
+    const resolvedOrigin = path.resolve(origin);
+    const byPath = allSources.filter((s) => s.kind === "mounted" && path.resolve(s.path) === resolvedOrigin);
+    if (byPath.length > 0)
+        return byPath;
+    // No match — origin may be remote/uninstalled
+    return [];
+}
+/**
+ * Check whether an origin refers to something that could be fetched remotely
+ * (i.e. it looks like a registry ref but isn't installed locally).
+ */
+export function isRemoteOrigin(origin, allSources) {
+    if (origin === "local")
+        return false;
+    return resolveSourcesForOrigin(origin, allSources).length === 0;
+}

package/dist/src/registry-install.d.ts

@@ -5,7 +5,7 @@ export interface InstallRegistryRefOptions {
     now?: Date;
 }
 export declare function installRegistryRef(ref: string, options?: InstallRegistryRefOptions): Promise<RegistryInstallResult>;
-export declare function upsertInstalledRegistryEntry(entry: RegistryInstalledEntry, stashDir?: string): AgentikitConfig;
-export declare function removeInstalledRegistryEntry(id: string, stashDir?: string): AgentikitConfig;
+export declare function upsertInstalledRegistryEntry(entry: RegistryInstalledEntry): AgentikitConfig;
+export declare function removeInstalledRegistryEntry(id: string): AgentikitConfig;
 export declare function getRegistryCacheRootDir(): string;
 export declare function detectStashRoot(extractedDir: string): string;