agentikit 0.0.12 → 0.0.14

package/dist/paths.js

@@ -0,0 +1,82 @@
+/**
+ * Centralized path resolution for all agentikit directories.
+ *
+ * Provides platform-aware paths for config, cache, and stash directories,
+ * following XDG Base Directory conventions on Unix and standard locations
+ * on Windows.
+ */
+import path from "node:path";
+const IS_WINDOWS = process.platform === "win32";
+// ── Config directory ─────────────────────────────────────────────────────────
+export function getConfigDir(env = process.env, platform = process.platform) {
+    if (platform === "win32") {
+        const appData = env.APPDATA?.trim();
+        if (appData)
+            return path.join(appData, "agentikit");
+        const userProfile = env.USERPROFILE?.trim();
+        if (!userProfile) {
+            throw new Error("Unable to determine config directory. Set APPDATA or USERPROFILE.");
+        }
+        return path.join(userProfile, "AppData", "Roaming", "agentikit");
+    }
+    const xdgConfigHome = env.XDG_CONFIG_HOME?.trim();
+    if (xdgConfigHome)
+        return path.join(xdgConfigHome, "agentikit");
+    const home = env.HOME?.trim();
+    if (!home) {
+        throw new Error("Unable to determine config directory. Set XDG_CONFIG_HOME or HOME.");
+    }
+    return path.join(home, ".config", "agentikit");
+}
+export function getConfigPath() {
+    return path.join(getConfigDir(), "config.json");
+}
+// ── Cache directory ──────────────────────────────────────────────────────────
+export function getCacheDir() {
+    if (IS_WINDOWS) {
+        const localAppData = process.env.LOCALAPPDATA?.trim();
+        if (localAppData)
+            return path.join(localAppData, "agentikit");
+        const userProfile = process.env.USERPROFILE?.trim();
+        if (userProfile)
+            return path.join(userProfile, "AppData", "Local", "agentikit");
+        const appData = process.env.APPDATA?.trim();
+        if (!appData) {
+            throw new Error("Unable to determine cache directory. Set LOCALAPPDATA, USERPROFILE, or APPDATA.");
+        }
+        return path.join(appData, "..", "Local", "agentikit");
+    }
+    const xdgCacheHome = process.env.XDG_CACHE_HOME?.trim();
+    if (xdgCacheHome)
+        return path.join(xdgCacheHome, "agentikit");
+    const home = process.env.HOME?.trim();
+    if (!home)
+        return path.join("/tmp", "agentikit-cache");
+    return path.join(home, ".cache", "agentikit");
+}
+export function getDbPath() {
+    return path.join(getCacheDir(), "index.db");
+}
+export function getRegistryCacheDir() {
+    return path.join(getCacheDir(), "registry");
+}
+export function getRegistryIndexCacheDir() {
+    return path.join(getCacheDir(), "registry-index");
+}
+export function getBinDir() {
+    return path.join(getCacheDir(), "bin");
+}
+// ── Default stash directory ──────────────────────────────────────────────────
+export function getDefaultStashDir() {
+    if (IS_WINDOWS) {
+        const userProfile = process.env.USERPROFILE?.trim();
+        if (userProfile)
+            return path.join(userProfile, "Documents", "agentikit");
+        return path.join("C:\\", "agentikit");
+    }
+    const home = process.env.HOME?.trim();
+    if (!home) {
+        throw new Error("Unable to determine default stash directory. Set HOME.");
+    }
+    return path.join(home, "agentikit");
+}

package/dist/{src/registry-install.js → registry-install.js}

@@ -1,23 +1,55 @@
+import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithTimeout, isWithin, TYPE_DIRS } from "./common";
+import { fetchWithRetry, isWithin, TYPE_DIRS } from "./common";
 import { loadConfig, saveConfig } from "./config";
 import { parseRegistryRef, resolveRegistryArtifact } from "./registry-resolve";
+import { getRegistryCacheDir as _getRegistryCacheDir } from "./paths";
 const REGISTRY_STASH_DIR_NAMES = new Set(Object.values(TYPE_DIRS));
 export async function installRegistryRef(ref, options) {
     const parsed = parseRegistryRef(ref);
+    if (parsed.source === "local") {
+        return installLocalRegistryRef(parsed, options);
+    }
     if (parsed.source === "git") {
         return installGitRegistryRef(parsed, options);
     }
     const resolved = await resolveRegistryArtifact(parsed);
     const installedAt = (options?.now ?? new Date()).toISOString();
     const cacheRootDir = options?.cacheRootDir ?? getRegistryCacheRootDir();
-    const cacheDir = buildInstallCacheDir(cacheRootDir, resolved.source, resolved.id);
+    const cacheDir = buildInstallCacheDir(cacheRootDir, resolved.source, resolved.id, resolved.resolvedVersion ?? resolved.resolvedRevision);
     const archivePath = path.join(cacheDir, "artifact.tar.gz");
     const extractedDir = path.join(cacheDir, "extracted");
+    // Check for cache hit: if extracted dir already exists and has a valid stash root, reuse it
+    if (isDirectory(extractedDir)) {
+        try {
+            const cachedStashRoot = detectStashRoot(extractedDir);
+            if (cachedStashRoot) {
+                const integrity = fs.existsSync(archivePath) ? await computeFileHash(archivePath) : undefined;
+                return {
+                    id: resolved.id,
+                    source: resolved.source,
+                    ref: resolved.ref,
+                    artifactUrl: resolved.artifactUrl,
+                    resolvedVersion: resolved.resolvedVersion,
+                    resolvedRevision: resolved.resolvedRevision,
+                    installedAt,
+                    cacheDir,
+                    extractedDir,
+                    stashRoot: cachedStashRoot,
+                    integrity,
+                };
+            }
+        }
+        catch {
+            // Cache invalid, re-download
+        }
+    }
     fs.mkdirSync(cacheDir, { recursive: true });
     await downloadArchive(resolved.artifactUrl, archivePath);
+    verifyArchiveIntegrity(archivePath, resolved.resolvedRevision, resolved.source);
+    const integrity = await computeFileHash(archivePath);
     extractTarGzSecure(archivePath, extractedDir);
     const provisionalKitRoot = detectStashRoot(extractedDir);
     const installRoot = applyAgentikitIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
@@ -33,9 +65,10 @@ export async function installRegistryRef(ref, options) {
         cacheDir,
         extractedDir,
         stashRoot,
+        integrity,
     };
 }
-async function installGitRegistryRef(parsed, options) {
+async function installLocalRegistryRef(parsed, options) {
     const resolved = await resolveRegistryArtifact(parsed);
     const installedAt = (options?.now ?? new Date()).toISOString();
     const cacheRootDir = options?.cacheRootDir ?? getRegistryCacheRootDir();
@@ -44,7 +77,8 @@ async function installGitRegistryRef(parsed, options) {
     fs.mkdirSync(cacheDir, { recursive: true });
     fs.rmSync(extractedDir, { recursive: true, force: true });
     fs.mkdirSync(extractedDir, { recursive: true });
-    const includeConfig = findNearestAgentikitIncludeConfig(parsed.sourcePath, parsed.repoRoot);
+    const searchRoot = parsed.repoRoot ?? parsed.sourcePath;
+    const includeConfig = findNearestAgentikitIncludeConfig(parsed.sourcePath, searchRoot);
     if (includeConfig) {
         copyIncludedPaths(includeConfig.baseDir, includeConfig.include, extractedDir);
     }
@@ -65,6 +99,70 @@ async function installGitRegistryRef(parsed, options) {
         stashRoot,
     };
 }
+async function installGitRegistryRef(parsed, options) {
+    const resolved = await resolveRegistryArtifact(parsed);
+    const installedAt = (options?.now ?? new Date()).toISOString();
+    const cacheRootDir = options?.cacheRootDir ?? getRegistryCacheRootDir();
+    const cacheDir = buildInstallCacheDir(cacheRootDir, parsed.source, parsed.id, resolved.resolvedRevision);
+    const cloneDir = path.join(cacheDir, "clone");
+    const extractedDir = path.join(cacheDir, "extracted");
+    // Check for cache hit
+    if (isDirectory(extractedDir)) {
+        try {
+            const provisionalKitRoot = detectStashRoot(extractedDir);
+            const installRoot = applyAgentikitIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
+            const stashRoot = detectStashRoot(installRoot);
+            if (stashRoot) {
+                return {
+                    id: resolved.id,
+                    source: resolved.source,
+                    ref: resolved.ref,
+                    artifactUrl: resolved.artifactUrl,
+                    resolvedVersion: resolved.resolvedVersion,
+                    resolvedRevision: resolved.resolvedRevision,
+                    installedAt,
+                    cacheDir,
+                    extractedDir,
+                    stashRoot,
+                };
+            }
+        }
+        catch {
+            // Cache invalid, re-clone
+        }
+    }
+    fs.mkdirSync(cacheDir, { recursive: true });
+    const cloneArgs = ["clone", "--depth", "1"];
+    if (parsed.requestedRef) {
+        cloneArgs.push("--branch", parsed.requestedRef);
+    }
+    cloneArgs.push(parsed.url, cloneDir);
+    const cloneResult = spawnSync("git", cloneArgs, { encoding: "utf8", timeout: 120_000 });
+    if (cloneResult.status !== 0) {
+        const err = cloneResult.stderr?.trim() || cloneResult.error?.message || "unknown error";
+        throw new Error(`Failed to clone ${parsed.url}: ${err}`);
+    }
+    // Copy contents to extracted dir without .git
+    fs.mkdirSync(extractedDir, { recursive: true });
+    copyDirectoryContents(cloneDir, extractedDir);
+    // Clean up the clone dir
+    fs.rmSync(cloneDir, { recursive: true, force: true });
+    const provisionalKitRoot = detectStashRoot(extractedDir);
+    const installRoot = applyAgentikitIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
+    const stashRoot = detectStashRoot(installRoot);
+    return {
+        id: resolved.id,
+        source: resolved.source,
+        ref: resolved.ref,
+        artifactUrl: resolved.artifactUrl,
+        resolvedVersion: resolved.resolvedVersion,
+        resolvedRevision: resolved.resolvedRevision,
+        installedAt,
+        cacheDir,
+        extractedDir,
+        stashRoot,
+    };
+}
 export function upsertInstalledRegistryEntry(entry) {
     const current = loadConfig();
     const currentInstalled = current.registry?.installed ?? [];
@@ -89,15 +187,7 @@ export function removeInstalledRegistryEntry(id) {
     return nextConfig;
 }
 export function getRegistryCacheRootDir() {
-    const xdgCache = process.env.XDG_CACHE_HOME?.trim();
-    if (xdgCache) {
-        return path.join(path.resolve(xdgCache), "agentikit", "registry");
-    }
-    const home = process.env.HOME?.trim();
-    if (!home) {
-        throw new Error("Unable to determine cache directory. Set XDG_CACHE_HOME or HOME.");
-    }
-    return path.join(path.resolve(home), ".cache", "agentikit", "registry");
+    return _getRegistryCacheDir();
 }
 export function detectStashRoot(extractedDir) {
     const root = path.resolve(extractedDir);
@@ -117,10 +207,12 @@ export function detectStashRoot(extractedDir) {
         return shallowest;
     return root;
 }
-function buildInstallCacheDir(cacheRootDir, source, id) {
+function buildInstallCacheDir(cacheRootDir, source, id, version) {
     const slug = `${source}-${id.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "")}`;
-    const stamp = `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
-    return path.join(cacheRootDir, slug || source, stamp);
+    const versionSlug = source === "local"
+        ? `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
+        : (version?.replace(/[^a-zA-Z0-9_.-]+/g, "-") ?? `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`);
+    return path.join(cacheRootDir, slug || source, versionSlug);
 }
 function applyAgentikitIncludeConfig(sourceRoot, cacheDir, searchRoot = sourceRoot) {
     const includeConfig = findNearestAgentikitIncludeConfig(sourceRoot, searchRoot);
@@ -133,7 +225,7 @@ function applyAgentikitIncludeConfig(sourceRoot, cacheDir, searchRoot = sourceRo
     return selectedDir;
 }
 async function downloadArchive(url, destination) {
-    const response = await fetchWithTimeout(url, undefined, 120_000);
+    const response = await fetchWithRetry(url, undefined, { timeout: 120_000 });
     if (!response.ok) {
         throw new Error(`Failed to download archive (${response.status}) from ${url}`);
     }
@@ -149,6 +241,37 @@ async function downloadArchive(url, destination) {
         fs.writeFileSync(destination, Buffer.from(arrayBuffer));
     }
 }
+export function verifyArchiveIntegrity(archivePath, expected, source) {
+    if (!expected)
+        return;
+    // For GitHub and git sources, resolvedRevision is a commit SHA, not a content hash.
+    // Content integrity cannot be verified from a commit hash, so skip verification.
+    if (source === "github" || source === "git")
+        return;
+    const fileBuffer = fs.readFileSync(archivePath);
+    // SRI hash format: sha256-<base64> or sha512-<base64>
+    if (expected.startsWith("sha256-") || expected.startsWith("sha512-")) {
+        const dashIndex = expected.indexOf("-");
+        const algorithm = expected.slice(0, dashIndex);
+        const expectedBase64 = expected.slice(dashIndex + 1);
+        const actualBase64 = createHash(algorithm).update(fileBuffer).digest("base64");
+        if (actualBase64 !== expectedBase64) {
+            fs.unlinkSync(archivePath);
+            throw new Error(`Integrity check failed for ${archivePath}: expected ${algorithm} digest ${expectedBase64}, got ${actualBase64}`);
+        }
+        return;
+    }
+    // Hex shasum (SHA-1 from npm)
+    if (/^[0-9a-f]{40}$/i.test(expected)) {
+        const actualHex = createHash("sha1").update(fileBuffer).digest("hex");
+        if (actualHex.toLowerCase() !== expected.toLowerCase()) {
+            fs.unlinkSync(archivePath);
+            throw new Error(`Integrity check failed for ${archivePath}: expected sha1 ${expected}, got ${actualHex}`);
+        }
+        return;
+    }
+    // Unrecognized format — skip verification
+}
 function extractTarGzSecure(archivePath, destinationDir) {
     const listResult = spawnSync("tar", ["tzf", archivePath], { encoding: "utf8" });
     if (listResult.status !== 0) {
@@ -313,3 +436,8 @@ function normalizeInstalledEntry(entry) {
         cacheDir: path.resolve(entry.cacheDir),
     };
 }
+async function computeFileHash(filePath) {
+    const data = fs.readFileSync(filePath);
+    const hash = createHash("sha256").update(data).digest("hex");
+    return `sha256:${hash}`;
+}

package/dist/{src/registry-resolve.js → registry-resolve.js}

@@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { fetchWithTimeout } from "./common";
+import { fetchWithRetry } from "./common";
 import { GITHUB_API_BASE, githubHeaders, asRecord, asString } from "./github";
 export function parseRegistryRef(rawRef) {
     const ref = rawRef.trim();
@@ -14,12 +14,18 @@ export function parseRegistryRef(rawRef) {
     if (ref.startsWith("github:")) {
         return parseGithubShorthand(ref.slice(7), ref);
     }
+    if (ref.startsWith("git+")) {
+        return parseGitUrl(stripGitTransport(ref), ref);
+    }
+    if (ref.startsWith("file:")) {
+        return tryParseLocalRef(fileUriToPath(ref), true);
+    }
     if (ref.startsWith("http://") || ref.startsWith("https://")) {
-        return parseGithubUrl(ref);
+        return parseRemoteUrl(ref);
     }
-    const localGitRef = tryParseLocalGitRef(ref, isPathLikeRef(ref));
-    if (localGitRef) {
-        return localGitRef;
+    const localRef = tryParseLocalRef(ref, isPathLikeRef(ref));
+    if (localRef) {
+        return localRef;
     }
     if (ref.startsWith("@") || !looksLikeGithubOwnerRepo(ref)) {
         return parseNpmRef(ref, ref);
@@ -30,6 +36,9 @@ export async function resolveRegistryArtifact(parsed) {
     if (parsed.source === "npm") {
         return resolveNpmArtifact(parsed);
     }
+    if (parsed.source === "local") {
+        return resolveLocalArtifact(parsed);
+    }
     if (parsed.source === "git") {
         return resolveGitArtifact(parsed);
     }
@@ -69,7 +78,7 @@ function parseGithubShorthand(input, originalRef) {
         requestedRef,
     };
 }
-function parseGithubUrl(rawUrl) {
+function parseRemoteUrl(rawUrl) {
     let url;
     try {
         url = new URL(rawUrl);
@@ -77,9 +86,12 @@ function parseGithubUrl(rawUrl) {
     catch {
         throw new Error("Invalid registry URL.");
     }
-    if (url.hostname !== "github.com") {
-        throw new Error("Only GitHub URLs are currently supported for URL refs.");
+    if (url.hostname === "github.com") {
+        return parseGithubUrl(url, rawUrl);
     }
+    return parseGitUrl(rawUrl, rawUrl);
+}
+function parseGithubUrl(url, rawUrl) {
     const segments = url.pathname.split("/").filter(Boolean);
     if (segments.length < 2) {
         throw new Error("Invalid GitHub URL. Expected https://github.com/owner/repo.");
@@ -96,7 +108,21 @@ function parseGithubUrl(rawUrl) {
         requestedRef,
     };
 }
-function tryParseLocalGitRef(rawRef, explicitPath) {
+function parseGitUrl(input, originalRef) {
+    const [urlPart, requestedRef] = splitRefSuffix(input.trim());
+    if (!urlPart)
+        throw new Error("Invalid git ref. A URL is required.");
+    // Normalize the URL for the id (strip .git suffix, fragment)
+    const normalized = urlPart.replace(/\.git$/i, "");
+    return {
+        source: "git",
+        ref: originalRef,
+        id: `git:${normalized}`,
+        url: urlPart,
+        requestedRef,
+    };
+}
+function tryParseLocalRef(rawRef, explicitPath) {
     if (!explicitPath) {
         return undefined;
     }
@@ -112,13 +138,10 @@ function tryParseLocalGitRef(rawRef, explicitPath) {
         throw new Error("Local add path must be a directory, but the provided path is not one.");
     }
     const repoRoot = findGitRepoRoot(resolvedPath);
-    if (!repoRoot) {
-        throw new Error("Local add path must be inside a git repository.");
-    }
     return {
-        source: "git",
+        source: "local",
         ref: rawRef,
-        id: `git:${encodeURIComponent(resolvedPath)}`,
+        id: `local:${encodeURIComponent(resolvedPath)}`,
         repoRoot,
         sourcePath: resolvedPath,
     };
@@ -145,7 +168,13 @@ async function resolveNpmArtifact(parsed) {
         resolvedVersion = requested;
     }
     else {
+        // Try dist-tag first
         resolvedVersion = asString(distTags[requested]);
+        // If not a dist-tag, try semver range resolution
+        if (!resolvedVersion && isSemverRange(requested)) {
+            const versionKeys = Object.keys(versions).filter(isExactSemver);
+            resolvedVersion = maxSatisfying(versionKeys, requested);
+        }
     }
     if (!resolvedVersion || !(resolvedVersion in versions)) {
         throw new Error(`Unable to resolve npm ref \"${parsed.ref}\".`);
@@ -210,13 +239,30 @@ async function resolveGithubArtifact(parsed) {
     };
 }
 async function resolveGitArtifact(parsed) {
+    const ref = parsed.requestedRef ?? "HEAD";
+    const result = spawnSync("git", ["ls-remote", parsed.url, ref], { encoding: "utf8", timeout: 30_000 });
+    let resolvedRevision;
+    if (result.status === 0) {
+        const firstLine = result.stdout.trim().split(/\r?\n/)[0];
+        resolvedRevision = firstLine?.split(/\s/)[0] || undefined;
+    }
+    return {
+        id: parsed.id,
+        source: parsed.source,
+        ref: parsed.ref,
+        artifactUrl: parsed.url,
+        resolvedVersion: parsed.requestedRef,
+        resolvedRevision,
+    };
+}
+async function resolveLocalArtifact(parsed) {
     return {
         id: parsed.id,
         source: parsed.source,
         ref: parsed.ref,
         artifactUrl: pathToFileURL(parsed.sourcePath).toString(),
-        resolvedRevision: readGitValue(parsed.repoRoot, "rev-parse", "HEAD"),
-        resolvedVersion: readGitValue(parsed.repoRoot, "rev-parse", "--abbrev-ref", "HEAD"),
+        resolvedRevision: parsed.repoRoot ? readGitValue(parsed.repoRoot, "rev-parse", "HEAD") : undefined,
+        resolvedVersion: parsed.repoRoot ? readGitValue(parsed.repoRoot, "rev-parse", "--abbrev-ref", "HEAD") : undefined,
     };
 }
 function splitNpmNameAndVersion(input) {
@@ -265,6 +311,30 @@ function splitRefSuffix(value) {
         return [value, undefined];
     return [value.slice(0, hash), value.slice(hash + 1) || undefined];
 }
+/**
+ * Strip the `git+` transport prefix from a ref, returning the inner URL.
+ * Handles `git+https://...`, `git+ssh://...`, `git+http://...`, etc.
+ */
+function stripGitTransport(ref) {
+    return ref.slice(4); // strip "git+"
+}
+/**
+ * Convert a `file:` URI to a local filesystem path.
+ * Supports `file:./relative`, `file:../relative`, and `file:///absolute`.
+ */
+function fileUriToPath(ref) {
+    const after = ref.slice(5); // strip "file:"
+    // file:///absolute/path or file:///C:/path
+    if (after.startsWith("///")) {
+        return after.slice(2); // keep one leading /
+    }
+    // file://hostname/path (rare, treat hostname/path as absolute)
+    if (after.startsWith("//")) {
+        return after.slice(1);
+    }
+    // file:./relative or file:../relative or file:/absolute
+    return after;
+}
 function findGitRepoRoot(startDir) {
     let current = path.resolve(startDir);
     while (true) {
@@ -284,15 +354,105 @@ function readGitValue(repoRoot, ...args) {
     const value = result.stdout.trim();
     return value || undefined;
 }
+function parseSemver(version) {
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
+    if (!match)
+        return undefined;
+    return {
+        major: parseInt(match[1], 10),
+        minor: parseInt(match[2], 10),
+        patch: parseInt(match[3], 10),
+        prerelease: match[4],
+    };
+}
+function isExactSemver(version) {
+    return /^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.+-]+)?$/.test(version);
+}
+function isSemverRange(input) {
+    return /^[~^>=<*]/.test(input) || /^\d+\.(\d+|\*)/.test(input);
+}
+function compareSemver(a, b) {
+    if (a.major !== b.major)
+        return a.major - b.major;
+    if (a.minor !== b.minor)
+        return a.minor - b.minor;
+    if (a.patch !== b.patch)
+        return a.patch - b.patch;
+    // Versions with prerelease are lower than release
+    if (a.prerelease && !b.prerelease)
+        return -1;
+    if (!a.prerelease && b.prerelease)
+        return 1;
+    return 0;
+}
+function semverGte(a, b) {
+    return compareSemver(a, b) >= 0;
+}
+function satisfiesRange(version, range) {
+    // Skip pre-release versions unless range specifically mentions one
+    if (version.prerelease && !range.includes("-"))
+        return false;
+    // ^1.2.3 — compatible with version: same major, >= minor.patch
+    const caretMatch = range.match(/^\^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
+    if (caretMatch) {
+        const rMajor = parseInt(caretMatch[1], 10);
+        const rMinor = parseInt(caretMatch[2], 10);
+        const rPatch = parseInt(caretMatch[3], 10);
+        if (version.major !== rMajor)
+            return false;
+        // ^0.x has special behavior: ^0.2.3 means >=0.2.3 <0.3.0
+        if (rMajor === 0) {
+            if (version.minor !== rMinor)
+                return false;
+            return version.patch >= rPatch;
+        }
+        return semverGte(version, { major: rMajor, minor: rMinor, patch: rPatch });
+    }
+    // ~1.2.3 — same major.minor, patch >= specified
+    const tildeMatch = range.match(/^~(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
+    if (tildeMatch) {
+        const rMajor = parseInt(tildeMatch[1], 10);
+        const rMinor = parseInt(tildeMatch[2], 10);
+        const rPatch = parseInt(tildeMatch[3], 10);
+        return version.major === rMajor && version.minor === rMinor && version.patch >= rPatch;
+    }
+    // >=1.2.3
+    const gteMatch = range.match(/^>=(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
+    if (gteMatch) {
+        const rMajor = parseInt(gteMatch[1], 10);
+        const rMinor = parseInt(gteMatch[2], 10);
+        const rPatch = parseInt(gteMatch[3], 10);
+        return semverGte(version, { major: rMajor, minor: rMinor, patch: rPatch });
+    }
+    // * or latest
+    if (range === "*" || range === "latest")
+        return true;
+    return false;
+}
+export function maxSatisfying(versions, range) {
+    const candidates = [];
+    for (const v of versions) {
+        const parsed = parseSemver(v);
+        if (!parsed)
+            continue;
+        if (satisfiesRange(parsed, range)) {
+            candidates.push({ version: v, parsed });
+        }
+    }
+    if (candidates.length === 0)
+        return undefined;
+    candidates.sort((a, b) => compareSemver(b.parsed, a.parsed));
+    return candidates[0].version;
+}
 async function fetchJson(url, headers) {
-    const response = await fetchWithTimeout(url, { headers });
+    const response = await fetchWithRetry(url, { headers });
     if (!response.ok) {
         throw new Error(`Request failed (${response.status}) for ${url}`);
     }
     return await response.json();
 }
 async function tryFetchJson(url, headers) {
-    const response = await fetchWithTimeout(url, { headers });
+    const response = await fetchWithRetry(url, { headers });
     if (!response.ok)
         return null;
     return await response.json();

package/dist/{src/registry-search.js → registry-search.js}

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithTimeout } from "./common";
+import { fetchWithRetry } from "./common";
+import { getRegistryIndexCacheDir } from "./paths";
 // ── Constants ───────────────────────────────────────────────────────────────
 /** Default registry index URL. Override via config or AKM_REGISTRY_URL env var. */
 const DEFAULT_REGISTRY_URL = "https://raw.githubusercontent.com/itlackey/agentikit-registry/main/index.json";
@@ -44,7 +45,7 @@ async function loadIndex(url) {
     }
     // Try to fetch fresh index
     try {
-        const response = await fetchWithTimeout(url, undefined, 10_000);
+        const response = await fetchWithRetry(url, undefined, { timeout: 10_000 });
         if (!response.ok) {
             throw new Error(`HTTP ${response.status}`);
         }
@@ -90,22 +91,13 @@ function writeCachedIndex(cachePath, index) {
     }
 }
 function indexCachePath(url) {
-    const cacheRoot = resolveCacheDir();
+    const indexDir = getRegistryIndexCacheDir();
     // Deterministic filename from URL
     const slug = url
         .replace(/[^a-zA-Z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "")
         .slice(0, 120);
-    return path.join(cacheRoot, "registry-index", `${slug}.json`);
-}
-function resolveCacheDir() {
-    const xdgCache = process.env.XDG_CACHE_HOME?.trim();
-    if (xdgCache)
-        return path.join(path.resolve(xdgCache), "agentikit");
-    const home = process.env.HOME?.trim();
-    if (!home)
-        return path.join("/tmp", "agentikit-cache");
-    return path.join(path.resolve(home), ".cache", "agentikit");
+    return path.join(indexDir, `${slug}.json`);
 }
 function isCacheExpired(mtimeMs) {
     return Date.now() - mtimeMs > CACHE_TTL_MS;
@@ -248,9 +240,9 @@ function asString(value) {
     return typeof value === "string" && value ? value : undefined;
 }
 function asSource(value) {
-    return value === "npm" || value === "github" || value === "git"
-        ? value
-        : undefined;
+    if (value === "npm" || value === "github" || value === "git" || value === "local")
+        return value;
+    return undefined;
 }
 function asStringArray(value) {
     if (!Array.isArray(value))