@alan-ai-hq/agent-manager 0.1.113 → 0.1.115

package/dist/skills/runtime-skill-manager.js

@@ -0,0 +1,934 @@
+import { Buffer } from "node:buffer";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { cp, lstat, mkdir, readdir, readFile, readlink, rename, rm, stat, symlink, writeFile, } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { inspectSkillPackage, readSkillPackageFile } from "@alan-ai/shared/node/skill-package";
+import { desiredSkillManifestSchema, SKILL_PACKAGE_LIMITS, SKILLS_PROTOCOL_VERSION, } from "@alan-ai/shared/skills";
+import { LocalSkillSource } from "./local-skill-source.js";
+import { ManagedSkillStore } from "./managed-skill-store.js";
+import { createSkillBundle, extractSkillBundle } from "./skill-bundle.js";
+import { uploadPreparedSkillBundle } from "./skill-control-client.js";
+export class RuntimeSkillManager {
+    skillsStateDirectory;
+    managedSkillsDirectory;
+    compatibilitySkillsDirectory;
+    legacyManifestPath;
+    storageNamespace;
+    store;
+    downloadBundle;
+    localSource;
+    controlClient;
+    reconcileTail = Promise.resolve();
+    constructor(skillsStateDirectory, managedSkillsDirectory, compatibilitySkillsDirectory, legacyManifestPath, storageNamespace, store, downloadBundle, localSource, controlClient) {
+        this.skillsStateDirectory = skillsStateDirectory;
+        this.managedSkillsDirectory = managedSkillsDirectory;
+        this.compatibilitySkillsDirectory = compatibilitySkillsDirectory;
+        this.legacyManifestPath = legacyManifestPath;
+        this.storageNamespace = storageNamespace;
+        this.store = store;
+        this.downloadBundle = downloadBundle;
+        this.localSource = localSource;
+        this.controlClient = controlClient;
+    }
+    static async open(options) {
+        const storageNamespace = resolveStorageNamespace(options.endpointProfile, options.profileStorageIdentity);
+        const skillsStateDirectory = storageNamespace
+            ? join(options.homeDirectory, ".alan", "skills", "profiles", storageNamespace)
+            : join(options.homeDirectory, ".alan", "skills");
+        const managedSkillsDirectory = join(options.homeDirectory, ".agents", "skills");
+        const store = await ManagedSkillStore.open(skillsStateDirectory);
+        return new RuntimeSkillManager(skillsStateDirectory, managedSkillsDirectory, join(options.homeDirectory, ".claude", "skills"), join(options.homeDirectory, ".alan", "sync-manifest.json"), storageNamespace, store, options.downloadBundle ?? downloadBundleWithFetch, options.localSource ?? new LocalSkillSource(), options.controlClient);
+    }
+    async scan(input) {
+        const outcome = await this.localSource.scan(input);
+        if (outcome.status === "complete") {
+            await this.store.recordCompleteScan({
+                revision: outcome.inventoryRevision,
+                candidates: outcome.candidates.map((candidate) => {
+                    const absolutePath = this.localSource.resolvePackage(candidate.localKey);
+                    if (!absolutePath)
+                        throw new Error(`Complete scan lost source for ${candidate.localKey}`);
+                    return {
+                        localKey: candidate.localKey,
+                        absolutePath,
+                        contentHash: candidate.contentHash,
+                    };
+                }),
+            });
+        }
+        return outcome;
+    }
+    async publish(input) {
+        const source = this.store.resolveSource(input.localKey);
+        if (!source)
+            throw new Error("Skill source is not present in the last complete scan");
+        if (source.contentHash !== input.expectedContentHash) {
+            throw new Error("Skill source changed after the preview was requested; refresh and review again");
+        }
+        if (Date.parse(input.uploadGrant.expiresAt) <= Date.now()) {
+            throw new Error("Skill upload grant expired; retry the preview");
+        }
+        const bundle = await createSkillBundle(source.absolutePath);
+        if (bundle.contentHash !== input.expectedContentHash) {
+            throw new Error("Skill source changed while preparing the preview; refresh and review again");
+        }
+        if (bundle.bytes.byteLength > input.uploadGrant.maxBytes) {
+            throw new Error("Prepared Skill bundle exceeds its upload grant limit");
+        }
+        await (this.controlClient
+            ? this.controlClient.uploadPreparedBundle(input.uploadGrant, bundle.bytes)
+            : uploadPreparedSkillBundle(input.uploadGrant, bundle.bytes));
+        return {
+            commandId: input.commandId,
+            previewId: input.previewId,
+            localKey: input.localKey,
+            contentHash: bundle.contentHash,
+            archiveHash: bundle.archiveHash,
+            compressedBytes: bundle.bytes.byteLength,
+            state: "uploaded",
+        };
+    }
+    async inspectLocalPackage(input) {
+        const source = this.requireCurrentLocalSource(input);
+        const inspected = await this.localSource.inspectPackage(source.absolutePath, input.expectedContentHash);
+        if (inspected.contentHash !== input.expectedContentHash) {
+            throw new Error("Skill source changed after the last scan; scan folders again");
+        }
+        const preview = {
+            localKey: input.localKey,
+            package: {
+                path: inspected.metadata.name,
+                name: inspected.metadata.name,
+                description: inspected.metadata.description,
+                contentHash: inspected.contentHash,
+                fileCount: inspected.fileCount,
+                totalBytes: inspected.totalBytes,
+                files: inspected.files,
+                diagnostics: inspected.diagnostics,
+            },
+        };
+        return preview;
+    }
+    async readLocalPackageFile(input) {
+        const source = this.requireCurrentLocalSource(input);
+        const { file, bytes } = await readSkillPackageFile(source.absolutePath, input.path, input.expectedFileHash);
+        if (file.preview === "markdown" || file.preview === "text" || file.preview === "code") {
+            return {
+                file,
+                encoding: "utf8",
+                content: new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+                mediaType: localTextMediaType(file.path),
+            };
+        }
+        const mediaType = localRasterMediaType(file.path);
+        if (file.preview === "image" && mediaType && bytes.byteLength <= 2 * 1024 * 1024) {
+            return { file, encoding: "base64", content: bytes.toString("base64"), mediaType };
+        }
+        return { file, encoding: "metadata", ...(mediaType ? { mediaType } : {}) };
+    }
+    requireCurrentLocalSource(input) {
+        const source = this.store.resolveSource(input.localKey);
+        if (!source)
+            throw new Error("Skill source is not present in the last complete scan");
+        if (source.contentHash !== input.expectedContentHash) {
+            throw new Error("Skill source changed after the last scan; scan folders again");
+        }
+        return source;
+    }
+    async reconcile(input) {
+        return this.runExclusively(() => this.withMachineLock(() => this.reconcileUnlocked(input.manifest)));
+    }
+    async resolveConflict(input) {
+        return this.runExclusively(() => this.withMachineLock(() => this.resolveConflictUnlocked(input)));
+    }
+    async inspect() {
+        const status = this.store.inspect();
+        return {
+            stateIntegrity: status.integrity,
+            appliedRevision: status.appliedRevision,
+            projectionCount: status.projectionCount,
+        };
+    }
+    /**
+     * Resolve a server-authorized invocation to the exact package currently on disk.
+     * Display names are deliberately ignored: identity and observed content must match.
+     */
+    async resolveInvocation(runtimeId, invocation) {
+        if (invocation.kind === "local_skill") {
+            if (invocation.runtimeId !== runtimeId) {
+                throw new Error("Selected local Skill belongs to a different runtime");
+            }
+            const source = this.store.resolveSource(invocation.localKey);
+            if (!source || source.contentHash !== invocation.contentHash) {
+                throw new Error("Selected local Skill is no longer present in the last complete scan");
+            }
+            const inspected = await inspectSkillPackage(source.absolutePath, { expectedName: null });
+            if (inspected.contentHash !== invocation.contentHash) {
+                throw new Error("Selected local Skill changed after it was chosen; refresh the picker");
+            }
+            return { invocation, packageDirectory: source.absolutePath };
+        }
+        const runtimeDirectory = this.store.runtimeDirectoryFor(invocation.skillId, invocation.versionId);
+        if (!runtimeDirectory) {
+            throw new Error("Selected Skill version is not installed on this runtime");
+        }
+        const packageDirectory = this.projectionDirectory(runtimeDirectory);
+        const marker = await readMarker(packageDirectory);
+        if (!marker ||
+            marker.skillId !== invocation.skillId ||
+            marker.versionId !== invocation.versionId) {
+            throw new Error("Selected Skill projection is missing or no longer owned by Alan");
+        }
+        const inspected = await inspectSkillPackage(packageDirectory, { expectedName: null });
+        if (inspected.contentHash !== marker.contentHash) {
+            throw new Error("Selected Skill projection failed its content verification");
+        }
+        return { invocation, packageDirectory };
+    }
+    async reconcileUnlocked(manifest) {
+        const desired = desiredSkillManifestSchema.parse(manifest);
+        await mkdir(this.managedSkillsDirectory, { recursive: true, mode: 0o700 });
+        await mkdir(join(this.skillsStateDirectory, "cache", "sha256"), {
+            recursive: true,
+            mode: 0o700,
+        });
+        await mkdir(join(this.skillsStateDirectory, "tmp"), { recursive: true, mode: 0o700 });
+        const results = [];
+        const nextProjections = {};
+        for (const entry of desired.skills) {
+            try {
+                requireSafeRuntimeDirectory(entry.runtimeDirectory);
+                await this.adoptLegacyProjection(entry);
+                await this.requireReplaceable(entry);
+                const observedHash = await this.reuseCurrentProjection(entry);
+                const appliedHash = observedHash ?? (await this.project(entry, await this.ensureCached(entry)));
+                nextProjections[entry.runtimeDirectory] = {
+                    skillId: entry.skillId,
+                    versionId: entry.versionId,
+                    contentHash: entry.contentHash,
+                };
+                results.push({
+                    skillId: entry.skillId,
+                    versionId: entry.versionId,
+                    contentHash: entry.contentHash,
+                    observedHash: appliedHash,
+                    state: "applied",
+                });
+            }
+            catch (error) {
+                const code = errorCode(error);
+                const conflict = isUnmanagedConflict(error)
+                    ? await this.observeConflict(entry, code).catch(() => null)
+                    : null;
+                results.push({
+                    skillId: entry.skillId,
+                    versionId: entry.versionId,
+                    contentHash: entry.contentHash,
+                    state: isUnmanagedConflict(error) ? "conflict" : "failed",
+                    errorCode: code,
+                    errorMessage: error instanceof Error ? error.message : String(error),
+                    ...(conflict ? { conflict } : {}),
+                });
+            }
+        }
+        if (results.every((result) => result.state === "applied")) {
+            results.push(...(await this.removeNoLongerDesired(nextProjections)));
+        }
+        if (results.every((result) => result.state === "applied")) {
+            await this.store.recordApplied({ revision: desired.revision, projections: nextProjections });
+            await this.retireLegacySyncManifest();
+        }
+        return {
+            attemptId: randomUUID(),
+            desiredRevision: desired.revision,
+            skills: results,
+        };
+    }
+    async resolveConflictUnlocked(input) {
+        const manifest = desiredSkillManifestSchema.parse(input.manifest);
+        const entry = manifest.skills.find((candidate) => candidate.skillId === input.skillId && candidate.versionId === input.versionId);
+        if (!entry || entry.runtimeDirectory !== input.expectedConflict.runtimeDirectory) {
+            return resolutionFailure(input, "stale", "SKILL_CONFLICT_STALE", "The Skill conflict changed. Refresh and try again.");
+        }
+        const current = await this.observeConflict(entry, input.expectedConflict.kind === "managed_destination"
+            ? "UNMANAGED_PATH_CONFLICT"
+            : "COMPATIBILITY_PATH_CONFLICT").catch(() => null);
+        if (!current || !sameConflict(current, input.expectedConflict)) {
+            return resolutionFailure(input, "stale", "SKILL_CONFLICT_STALE", "The local Skill changed. Refresh and try again.");
+        }
+        try {
+            if (input.resolution.kind === "rename_local") {
+                await this.renameLocalConflict(entry, current, input.resolution.name);
+                const reconciled = await this.reconcileUnlocked(manifest);
+                return resolutionFromReconcile(input, reconciled);
+            }
+            return await this.overwriteLocalConflict(input, entry, current, manifest);
+        }
+        catch (error) {
+            return resolutionFailure(input, errorCode(error) === "SKILL_CONFLICT_STALE" ? "stale" : "failed", errorCode(error), error instanceof Error ? error.message : String(error));
+        }
+    }
+    async observeConflict(entry, code) {
+        const kind = code === "COMPATIBILITY_PATH_CONFLICT" ? "compatibility_destination" : "managed_destination";
+        const directory = this.conflictDirectory(entry.runtimeDirectory, kind);
+        const inspected = await inspectSkillPackage(directory, { expectedName: null });
+        return {
+            kind,
+            runtimeDirectory: entry.runtimeDirectory,
+            observedHash: inspected.contentHash,
+            observedName: inspected.metadata.name,
+        };
+    }
+    conflictDirectory(runtimeDirectory, kind) {
+        requireSafeRuntimeDirectory(runtimeDirectory);
+        return join(kind === "managed_destination"
+            ? this.managedSkillsDirectory
+            : this.compatibilitySkillsDirectory, this.projectionDirectoryName(runtimeDirectory));
+    }
+    async renameLocalConflict(entry, conflict, name) {
+        requirePortableSkillName(name);
+        const source = this.conflictDirectory(entry.runtimeDirectory, conflict.kind);
+        const destination = join(dirname(source), name);
+        if (await pathExists(destination)) {
+            throw Object.assign(new Error(`A local Skill named ${name} already exists`), {
+                code: "SKILL_LOCAL_NAME_CONFLICT",
+            });
+        }
+        const suffix = `${process.pid}-${randomBytes(8).toString("hex")}`;
+        const backup = `${source}.rename-backup-${suffix}`;
+        const pending = `${source}.rename-pending-${suffix}`;
+        let sourceMoved = false;
+        let destinationInstalled = false;
+        try {
+            await rename(source, backup);
+            sourceMoved = true;
+            await cp(backup, pending, { recursive: true, errorOnExist: true, force: false });
+            const skillMarkdown = join(pending, "SKILL.md");
+            await writeFile(skillMarkdown, rewriteSkillMarkdownName(await readFile(skillMarkdown, "utf8"), name), {
+                encoding: "utf8",
+                mode: 0o644,
+            });
+            await inspectSkillPackage(pending, { expectedName: name });
+            await rename(pending, destination);
+            destinationInstalled = true;
+            await rm(backup, { recursive: true, force: true });
+        }
+        catch (error) {
+            if (destinationInstalled)
+                await rm(destination, { recursive: true, force: true });
+            if (sourceMoved && (await pathExists(backup)) && !(await pathExists(source))) {
+                await rename(backup, source);
+            }
+            throw error;
+        }
+        finally {
+            await rm(pending, { recursive: true, force: true });
+            if (!sourceMoved || destinationInstalled) {
+                await rm(backup, { recursive: true, force: true });
+            }
+        }
+    }
+    async overwriteLocalConflict(input, entry, conflict, manifest) {
+        const source = this.conflictDirectory(entry.runtimeDirectory, conflict.kind);
+        const backup = `${source}.overwrite-backup-${process.pid}-${randomBytes(8).toString("hex")}`;
+        await rename(source, backup);
+        try {
+            const reconciled = await this.reconcileUnlocked(manifest);
+            const result = resolutionFromReconcile(input, reconciled);
+            if (result.state !== "applied") {
+                await this.removeResolvedProjection(entry, conflict.kind);
+                await rename(backup, source);
+                return result;
+            }
+            await rm(backup, { recursive: true, force: true });
+            return result;
+        }
+        catch (error) {
+            await this.removeResolvedProjection(entry, conflict.kind).catch(() => undefined);
+            if (!(await pathExists(source)) && (await pathExists(backup)))
+                await rename(backup, source);
+            throw error;
+        }
+    }
+    async removeResolvedProjection(entry, conflictKind) {
+        const destination = this.conflictDirectory(entry.runtimeDirectory, conflictKind);
+        if (!(await pathExists(destination)))
+            return;
+        if (conflictKind === "managed_destination") {
+            const marker = await readMarker(destination);
+            if (marker?.skillId === entry.skillId &&
+                marker.versionId === entry.versionId &&
+                marker.contentHash === entry.contentHash) {
+                await rm(destination, { recursive: true, force: true });
+            }
+            return;
+        }
+        const canonical = this.projectionDirectory(entry.runtimeDirectory);
+        const projection = {
+            skillId: entry.skillId,
+            versionId: entry.versionId,
+            contentHash: entry.contentHash,
+        };
+        await removeCompatibilityProjection(destination, canonical, projection);
+    }
+    async reuseCurrentProjection(entry) {
+        const destination = this.projectionDirectory(entry.runtimeDirectory);
+        const marker = await readMarker(destination);
+        if (marker?.skillId !== entry.skillId ||
+            marker.versionId !== entry.versionId ||
+            marker.contentHash !== entry.contentHash ||
+            !(await packageMatches(destination, entry.contentHash))) {
+            return null;
+        }
+        await this.ensureCompatibilityProjection(entry, destination);
+        return entry.contentHash;
+    }
+    async adoptLegacyProjection(entry) {
+        if (this.storageNamespace)
+            return;
+        const destination = this.projectionDirectory(entry.runtimeDirectory);
+        if (await pathExists(destination))
+            return;
+        const manifest = await readLegacyManifest(this.legacyManifestPath);
+        const legacy = manifest?.skills[entry.slug];
+        if (!legacy)
+            return;
+        const source = join(this.managedSkillsDirectory, entry.slug);
+        if (!(await legacyFileMatches(source, legacy.hash)) ||
+            !(await packageMatches(source, entry.contentHash))) {
+            return;
+        }
+        await rename(source, destination);
+        try {
+            await writeFile(join(destination, ".alan-managed.json"), `${JSON.stringify(markerFor(entry), null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        }
+        catch (error) {
+            await rename(destination, source).catch(() => undefined);
+            throw error;
+        }
+        await removeExactLegacySkill(join(this.compatibilitySkillsDirectory, entry.slug), legacy.hash);
+    }
+    async retireLegacySyncManifest() {
+        if (this.storageNamespace)
+            return;
+        const manifest = await readLegacyManifest(this.legacyManifestPath);
+        if (!manifest)
+            return;
+        for (const [command, entry] of Object.entries(manifest.skills)) {
+            await removeExactLegacySkill(join(this.managedSkillsDirectory, command), entry.hash);
+            await removeExactLegacySkill(join(this.compatibilitySkillsDirectory, command), entry.hash);
+        }
+        await rm(this.legacyManifestPath, { force: true });
+    }
+    async ensureCached(entry) {
+        const cacheDirectory = join(this.skillsStateDirectory, "cache", "sha256", entry.contentHash.slice("sha256:".length));
+        if (await packageMatches(cacheDirectory, entry.contentHash))
+            return cacheDirectory;
+        await rm(cacheDirectory, { recursive: true, force: true });
+        const bytes = await this.downloadBundle(entry);
+        if (bytes.byteLength !== entry.compressedBytes) {
+            throw new Error(`Downloaded Skill bundle length ${bytes.byteLength} does not match ${entry.compressedBytes}`);
+        }
+        const pendingDirectory = join(this.skillsStateDirectory, "tmp", `cache-${process.pid}-${randomBytes(8).toString("hex")}`);
+        try {
+            await extractSkillBundle(bytes, pendingDirectory, {
+                expectedArchiveHash: entry.archiveHash,
+                expectedContentHash: entry.contentHash,
+            });
+            try {
+                await rename(pendingDirectory, cacheDirectory);
+            }
+            catch (error) {
+                if (!(await packageMatches(cacheDirectory, entry.contentHash)))
+                    throw error;
+            }
+        }
+        finally {
+            await rm(pendingDirectory, { recursive: true, force: true });
+        }
+        return cacheDirectory;
+    }
+    async project(entry, cacheDirectory) {
+        const destination = this.projectionDirectory(entry.runtimeDirectory);
+        const existing = await readMarker(destination);
+        if (existing?.skillId === entry.skillId &&
+            existing.versionId === entry.versionId &&
+            existing.contentHash === entry.contentHash &&
+            (await packageMatches(destination, entry.contentHash))) {
+            await this.ensureCompatibilityProjection(entry, destination);
+            return entry.contentHash;
+        }
+        const suffix = `${process.pid}-${randomBytes(8).toString("hex")}`;
+        const pending = join(this.managedSkillsDirectory, `.pending-${suffix}`);
+        const backup = join(this.managedSkillsDirectory, `.backup-${suffix}`);
+        let movedExisting = false;
+        let installedPending = false;
+        let completed = false;
+        try {
+            await cp(cacheDirectory, pending, { recursive: true, errorOnExist: true, force: false });
+            await writeFile(join(pending, ".alan-managed.json"), `${JSON.stringify(markerFor(entry), null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+            if (!(await packageMatches(pending, entry.contentHash))) {
+                throw new Error("Pending managed Skill projection failed content verification");
+            }
+            if (await pathExists(destination)) {
+                await rename(destination, backup);
+                movedExisting = true;
+            }
+            try {
+                await rename(pending, destination);
+                installedPending = true;
+            }
+            catch (error) {
+                if (movedExisting)
+                    await rename(backup, destination);
+                throw error;
+            }
+            const inspected = await inspectSkillPackage(destination, { expectedName: null });
+            if (inspected.contentHash !== entry.contentHash) {
+                throw new Error("Managed Skill projection does not match its expected content hash");
+            }
+            await this.ensureCompatibilityProjection(entry, destination);
+            completed = true;
+            await rm(backup, { recursive: true, force: true });
+            return inspected.contentHash;
+        }
+        catch (error) {
+            if (!completed && installedPending) {
+                await rm(destination, { recursive: true, force: true });
+                if (movedExisting && (await pathExists(backup)))
+                    await rename(backup, destination);
+            }
+            throw error;
+        }
+        finally {
+            await rm(pending, { recursive: true, force: true });
+            if (completed || !movedExisting) {
+                await rm(backup, { recursive: true, force: true });
+            }
+        }
+    }
+    async requireReplaceable(entry) {
+        const destination = this.projectionDirectory(entry.runtimeDirectory);
+        if (!(await pathExists(destination)))
+            return;
+        const marker = await readMarker(destination);
+        if (!marker)
+            throw unmanagedPathConflict(entry.runtimeDirectory);
+        if (marker.skillId === entry.skillId &&
+            marker.versionId === entry.versionId &&
+            marker.contentHash === entry.contentHash &&
+            (await packageMatches(destination, entry.contentHash))) {
+            return;
+        }
+        const recorded = this.store.projections()[entry.runtimeDirectory];
+        if (!recorded || !markerMatchesProjection(marker, recorded)) {
+            throw unmanagedPathConflict(entry.runtimeDirectory);
+        }
+    }
+    async removeNoLongerDesired(desired) {
+        const failures = [];
+        if (!this.store.inspect().canRemoveManagedFiles)
+            return failures;
+        for (const [runtimeDirectory, recorded] of Object.entries(this.store.projections())) {
+            if (desired[runtimeDirectory])
+                continue;
+            const destination = this.projectionDirectory(runtimeDirectory);
+            const compatibility = join(this.compatibilitySkillsDirectory, this.projectionDirectoryName(runtimeDirectory));
+            const marker = await readMarker(destination);
+            if (!(await pathExists(destination)))
+                continue;
+            if (marker && markerMatchesProjection(marker, recorded)) {
+                if (!(await removeCompatibilityProjection(compatibility, destination, recorded))) {
+                    failures.push({
+                        skillId: recorded.skillId,
+                        versionId: recorded.versionId,
+                        contentHash: recorded.contentHash,
+                        state: "conflict",
+                        errorCode: "COMPATIBILITY_PATH_CONFLICT",
+                        errorMessage: `Refusing to remove an unowned compatibility path: ${runtimeDirectory}`,
+                    });
+                    continue;
+                }
+                await rm(destination, { recursive: true, force: true });
+            }
+            else {
+                failures.push({
+                    skillId: recorded.skillId,
+                    versionId: recorded.versionId,
+                    contentHash: recorded.contentHash,
+                    state: "conflict",
+                    errorCode: "MANAGED_MARKER_MISMATCH",
+                    errorMessage: `Refusing to remove modified or unowned Skill directory: ${runtimeDirectory}`,
+                });
+            }
+        }
+        return failures;
+    }
+    async ensureCompatibilityProjection(entry, canonicalDirectory) {
+        await mkdir(this.compatibilitySkillsDirectory, { recursive: true, mode: 0o700 });
+        const destination = join(this.compatibilitySkillsDirectory, this.projectionDirectoryName(entry.runtimeDirectory));
+        if (await pathExists(destination)) {
+            if (await compatibilityProjectionMatches(destination, canonicalDirectory, entry))
+                return;
+            throw unmanagedCompatibilityConflict(entry.runtimeDirectory);
+        }
+        try {
+            await symlink(canonicalDirectory, destination, "dir");
+            return;
+        }
+        catch (error) {
+            if (!isSymlinkUnsupported(error))
+                throw error;
+        }
+        const pending = `${destination}.pending-${process.pid}-${randomBytes(6).toString("hex")}`;
+        try {
+            await cp(canonicalDirectory, pending, { recursive: true, errorOnExist: true, force: false });
+            await writeFile(join(pending, ".alan-compatibility.json"), `${JSON.stringify({ ...markerFor(entry), canonicalDirectory }, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+            await rename(pending, destination);
+        }
+        finally {
+            await rm(pending, { recursive: true, force: true });
+        }
+    }
+    async runExclusively(work) {
+        const previous = this.reconcileTail;
+        let release;
+        this.reconcileTail = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous;
+        try {
+            return await work();
+        }
+        finally {
+            release();
+        }
+    }
+    projectionDirectory(runtimeDirectory) {
+        return join(this.managedSkillsDirectory, this.projectionDirectoryName(runtimeDirectory));
+    }
+    projectionDirectoryName(runtimeDirectory) {
+        requireSafeRuntimeDirectory(runtimeDirectory);
+        return this.storageNamespace
+            ? `${runtimeDirectory}--alan-${this.storageNamespace}`
+            : runtimeDirectory;
+    }
+    async withMachineLock(work) {
+        await mkdir(this.skillsStateDirectory, { recursive: true, mode: 0o700 });
+        const lockDirectory = join(this.skillsStateDirectory, "manager.lock");
+        const deadline = Date.now() + 30_000;
+        while (true) {
+            try {
+                await mkdir(lockDirectory, { mode: 0o700 });
+                try {
+                    await writeFile(join(lockDirectory, "owner.json"), `${JSON.stringify({ pid: process.pid, acquiredAt: new Date().toISOString() })}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+                }
+                catch (error) {
+                    await rm(lockDirectory, { recursive: true, force: true });
+                    throw error;
+                }
+                break;
+            }
+            catch (error) {
+                if (!isAlreadyPresent(error))
+                    throw error;
+                const ageMs = await stat(lockDirectory)
+                    .then((metadata) => Date.now() - metadata.mtimeMs)
+                    .catch(() => 0);
+                if (ageMs > 15 * 60_000) {
+                    await rm(lockDirectory, { recursive: true, force: true });
+                    continue;
+                }
+                if (Date.now() >= deadline) {
+                    throw Object.assign(new Error("Another Skill synchronization is still running"), {
+                        code: "SKILL_MANAGER_BUSY",
+                    });
+                }
+                await new Promise((resolveDelay) => setTimeout(resolveDelay, 50));
+            }
+        }
+        try {
+            return await work();
+        }
+        finally {
+            await rm(lockDirectory, { recursive: true, force: true });
+        }
+    }
+}
+async function downloadBundleWithFetch(entry) {
+    if (entry.compressedBytes > SKILL_PACKAGE_LIMITS.maxArchiveBytes) {
+        throw new Error("Desired Skill bundle exceeds the compressed size limit");
+    }
+    const response = await fetch(entry.downloadUrl, { redirect: "error" });
+    if (!response.ok)
+        throw new Error(`Skill bundle download failed with HTTP ${response.status}`);
+    return Buffer.from(await response.arrayBuffer());
+}
+async function packageMatches(directory, expectedHash) {
+    try {
+        return ((await inspectSkillPackage(directory, { expectedName: null })).contentHash === expectedHash);
+    }
+    catch {
+        return false;
+    }
+}
+async function readMarker(directory) {
+    try {
+        const value = JSON.parse(await readFile(join(directory, ".alan-managed.json"), "utf8"));
+        if (typeof value !== "object" ||
+            value === null ||
+            !("protocolVersion" in value) ||
+            value.protocolVersion !== SKILLS_PROTOCOL_VERSION ||
+            !("skillId" in value) ||
+            typeof value.skillId !== "string" ||
+            !("versionId" in value) ||
+            typeof value.versionId !== "string" ||
+            !("contentHash" in value) ||
+            typeof value.contentHash !== "string" ||
+            !/^sha256:[a-f0-9]{64}$/.test(value.contentHash)) {
+            return null;
+        }
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+async function compatibilityProjectionMatches(destination, canonicalDirectory, entry) {
+    const metadata = await lstat(destination);
+    if (metadata.isSymbolicLink()) {
+        const target = await readlink(destination);
+        return resolve(dirname(destination), target) === resolve(canonicalDirectory);
+    }
+    if (!metadata.isDirectory())
+        return false;
+    const marker = await readCompatibilityMarker(destination);
+    return (marker?.canonicalDirectory === canonicalDirectory &&
+        marker.skillId === entry.skillId &&
+        marker.versionId === entry.versionId &&
+        marker.contentHash === entry.contentHash &&
+        (await packageMatches(destination, entry.contentHash)));
+}
+async function removeCompatibilityProjection(destination, canonicalDirectory, projection) {
+    if (!(await pathExists(destination)))
+        return true;
+    const metadata = await lstat(destination);
+    if (metadata.isSymbolicLink()) {
+        const target = await readlink(destination);
+        if (resolve(dirname(destination), target) !== resolve(canonicalDirectory))
+            return false;
+        await rm(destination, { force: true });
+        return true;
+    }
+    const marker = await readCompatibilityMarker(destination);
+    if (!marker || !markerMatchesProjection(marker, projection))
+        return false;
+    await rm(destination, { recursive: true, force: true });
+    return true;
+}
+async function readCompatibilityMarker(directory) {
+    try {
+        const value = JSON.parse(await readFile(join(directory, ".alan-compatibility.json"), "utf8"));
+        if (value.protocolVersion !== SKILLS_PROTOCOL_VERSION ||
+            typeof value.skillId !== "string" ||
+            typeof value.versionId !== "string" ||
+            !/^sha256:[a-f0-9]{64}$/.test(value.contentHash) ||
+            typeof value.canonicalDirectory !== "string") {
+            return null;
+        }
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+function markerFor(entry) {
+    return {
+        protocolVersion: SKILLS_PROTOCOL_VERSION,
+        skillId: entry.skillId,
+        versionId: entry.versionId,
+        contentHash: entry.contentHash,
+    };
+}
+async function readLegacyManifest(path) {
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        if (!value || typeof value !== "object" || !("skills" in value))
+            return null;
+        const skillsValue = value.skills;
+        if (!skillsValue || typeof skillsValue !== "object" || Array.isArray(skillsValue))
+            return null;
+        const entries = {};
+        for (const [command, raw] of Object.entries(skillsValue)) {
+            if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(command) ||
+                !raw ||
+                typeof raw !== "object" ||
+                !("hash" in raw) ||
+                typeof raw.hash !== "string" ||
+                !/^[a-f0-9]{16}$/.test(raw.hash)) {
+                return null;
+            }
+            entries[command] = { hash: raw.hash };
+        }
+        return { skills: entries };
+    }
+    catch {
+        return null;
+    }
+}
+async function legacyFileMatches(directory, expectedHash) {
+    try {
+        const metadata = await lstat(directory);
+        if (!metadata.isDirectory() || metadata.isSymbolicLink())
+            return false;
+        const content = await readFile(join(directory, "SKILL.md"));
+        return createHash("sha256").update(content).digest("hex").slice(0, 16) === expectedHash;
+    }
+    catch {
+        return false;
+    }
+}
+async function removeExactLegacySkill(directory, expectedHash) {
+    if (!(await legacyFileMatches(directory, expectedHash)))
+        return;
+    await rm(join(directory, "SKILL.md"), { force: true });
+    const remaining = await readdir(directory);
+    if (remaining.length === 0)
+        await rm(directory, { recursive: true, force: true });
+}
+function markerMatchesProjection(marker, projection) {
+    return (marker.skillId === projection.skillId &&
+        marker.versionId === projection.versionId &&
+        marker.contentHash === projection.contentHash);
+}
+function resolveStorageNamespace(endpointProfile, profileStorageIdentity) {
+    if (!endpointProfile)
+        return null;
+    if (endpointProfile === "production" || endpointProfile === "staging") {
+        return endpointProfile;
+    }
+    const identity = profileStorageIdentity?.trim();
+    if (!identity)
+        return endpointProfile;
+    const identityHash = createHash("sha256").update(identity).digest("hex").slice(0, 12);
+    return `${endpointProfile}-${identityHash}`;
+}
+function requireSafeRuntimeDirectory(value) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value) || value === "." || value === "..") {
+        throw new Error(`Unsafe managed Skill directory: ${value}`);
+    }
+}
+function requirePortableSkillName(value) {
+    if (!/^(?!-)(?!.*--)[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value) || value.length > 64) {
+        throw Object.assign(new Error("Local Skill names use lowercase letters, numbers, and single hyphens"), { code: "INVALID_SKILL_NAME" });
+    }
+}
+function rewriteSkillMarkdownName(markdown, name) {
+    const lineEnding = markdown.includes("\r\n") ? "\r\n" : "\n";
+    const lines = markdown.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---") {
+        throw Object.assign(new Error("The local Skill has invalid SKILL.md frontmatter"), {
+            code: "INVALID_FRONTMATTER",
+        });
+    }
+    const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+    const nameIndex = lines.findIndex((line, index) => index > 0 && index < end && /^name\s*:/.test(line));
+    if (end < 0 || nameIndex < 0) {
+        throw Object.assign(new Error("The local Skill has invalid SKILL.md frontmatter"), {
+            code: "INVALID_FRONTMATTER",
+        });
+    }
+    lines[nameIndex] = `name: ${name}`;
+    return lines.join(lineEnding);
+}
+function sameConflict(left, right) {
+    return (left.kind === right.kind &&
+        left.runtimeDirectory === right.runtimeDirectory &&
+        left.observedHash === right.observedHash &&
+        left.observedName === right.observedName);
+}
+function resolutionFromReconcile(input, result) {
+    const resolved = result.skills.find((candidate) => candidate.skillId === input.skillId && candidate.versionId === input.versionId);
+    if (resolved?.state === "applied") {
+        return {
+            commandId: input.commandId,
+            skillId: input.skillId,
+            versionId: input.versionId,
+            state: "applied",
+        };
+    }
+    return resolutionFailure(input, "failed", resolved?.errorCode ?? "SKILL_RECONCILE_FAILED", resolved?.errorMessage ?? "The Skill could not be installed after resolving the conflict");
+}
+function resolutionFailure(input, state, errorCodeValue, errorMessage) {
+    return {
+        commandId: input.commandId,
+        skillId: input.skillId,
+        versionId: input.versionId,
+        state,
+        errorCode: errorCodeValue,
+        errorMessage,
+    };
+}
+function localRasterMediaType(path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".gif"))
+        return "image/gif";
+    if (lower.endsWith(".jpeg") || lower.endsWith(".jpg"))
+        return "image/jpeg";
+    if (lower.endsWith(".png"))
+        return "image/png";
+    if (lower.endsWith(".webp"))
+        return "image/webp";
+    return null;
+}
+function localTextMediaType(path) {
+    return path.toLowerCase().endsWith(".md")
+        ? "text/markdown; charset=utf-8"
+        : "text/plain; charset=utf-8";
+}
+async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (isMissingPath(error))
+            return false;
+        throw error;
+    }
+}
+function unmanagedPathConflict(runtimeDirectory) {
+    return Object.assign(new Error(`Managed Skill destination is occupied by unowned files: ${runtimeDirectory}`), { code: "UNMANAGED_PATH_CONFLICT" });
+}
+function unmanagedCompatibilityConflict(runtimeDirectory) {
+    return Object.assign(new Error(`Claude compatibility destination is occupied by unowned files: ${runtimeDirectory}`), { code: "COMPATIBILITY_PATH_CONFLICT" });
+}
+function isUnmanagedConflict(error) {
+    return ["UNMANAGED_PATH_CONFLICT", "COMPATIBILITY_PATH_CONFLICT"].includes(errorCode(error));
+}
+function errorCode(error) {
+    if (typeof error === "object" && error !== null && "code" in error) {
+        const code = error.code;
+        if (typeof code === "string")
+            return code;
+    }
+    return "SKILL_RECONCILE_FAILED";
+}
+function isMissingPath(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function isAlreadyPresent(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "EEXIST");
+}
+function isSymlinkUnsupported(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return false;
+    return ["EACCES", "ENOSYS", "EPERM"].includes(String(error.code));
+}
+//# sourceMappingURL=runtime-skill-manager.js.map