odai-dsh-agent 0.2.5 → 0.2.7

package/preset/odai/runtime/skill-bundle.mjs

@@ -1,318 +1,328 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
-
+import { isUnknownRecord } from "./runtime-types.mjs";
 export const ODAI_RUNTIME_CONTRACT = 3;
 export const SKILL_MANIFEST_FILE = "manifest.json";
 export const SKILL_SOURCE_MODES = Object.freeze(["bundled", "auto", "user"]);
-
 const MANIFEST_FIELDS = new Set([
-  "schemaVersion",
-  "name",
-  "skillVersion",
-  "runtimeContract",
-  "requiredFiles",
+    "schemaVersion",
+    "name",
+    "skillVersion",
+    "runtimeContract",
+    "requiredFiles",
 ]);
 const REQUIRED_RUNTIME_FILES = Object.freeze([
-  "SKILL.md",
-  "assets/routing-roles/controller.md",
-  "assets/routing-roles/researcher.md",
-  "assets/routing-roles/planner.md",
-  "assets/routing-roles/executor.md",
-  "assets/routing-roles/reviewer.md",
-  "assets/routing-roles/frontend.md",
+    "SKILL.md",
+    "assets/routing-roles/controller.md",
+    "assets/routing-roles/researcher.md",
+    "assets/routing-roles/planner.md",
+    "assets/routing-roles/executor.md",
+    "assets/routing-roles/reviewer.md",
+    "assets/routing-roles/frontend.md",
 ]);
 const PROJECT_SOURCES = new Set(["project-dsh", "project-agents", "custom"]);
 const USER_SOURCES = new Set(["user-dsh", "user-agents"]);
 const VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/u;
-
 function assertPlainObject(value, field) {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    throw new TypeError(`${field} must be an object`);
-  }
-  return value;
+    if (!isUnknownRecord(value))
+        throw new TypeError(`${field} must be an object`);
+    return value;
+}
+function isSkillSourceMode(value) {
+    return typeof value === "string" && SKILL_SOURCE_MODES.includes(value);
 }
-
 export function parseSkillVersion(value, field = "skillVersion") {
-  if (typeof value !== "string") throw new TypeError(`${field} must be a string`);
-  const match = value.match(VERSION_PATTERN);
-  if (!match) throw new TypeError(`${field} must use SemVer 2.0.0 syntax`);
-  const prerelease = match[4] === undefined ? [] : match[4].split(".");
-  for (const identifier of prerelease) {
-    if (/^\d+$/u.test(identifier) && identifier.length > 1 && identifier.startsWith("0")) {
-      throw new TypeError(`${field} has a numeric prerelease identifier with a leading zero`);
+    if (typeof value !== "string")
+        throw new TypeError(`${field} must be a string`);
+    const match = value.match(VERSION_PATTERN);
+    if (!match)
+        throw new TypeError(`${field} must use SemVer 2.0.0 syntax`);
+    const prerelease = match[4] === undefined ? [] : match[4].split(".");
+    for (const identifier of prerelease) {
+        if (/^\d+$/u.test(identifier) && identifier.length > 1 && identifier.startsWith("0")) {
+            throw new TypeError(`${field} has a numeric prerelease identifier with a leading zero`);
+        }
     }
-  }
-  return Object.freeze({
-    core: Object.freeze(match.slice(1, 4)),
-    prerelease: Object.freeze(prerelease),
-  });
+    return Object.freeze({
+        core: Object.freeze([match[1], match[2], match[3]]),
+        prerelease: Object.freeze(prerelease),
+    });
 }
-
 function compareNumericIdentifier(left, right) {
-  if (left.length < right.length) return -1;
-  if (left.length > right.length) return 1;
-  if (left < right) return -1;
-  if (left > right) return 1;
-  return 0;
+    if (left.length < right.length)
+        return -1;
+    if (left.length > right.length)
+        return 1;
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
 }
-
 function comparePrerelease(left, right) {
-  if (left.length === 0 && right.length === 0) return 0;
-  if (left.length === 0) return 1;
-  if (right.length === 0) return -1;
-  const length = Math.max(left.length, right.length);
-  for (let index = 0; index < length; index += 1) {
-    const leftValue = left[index];
-    const rightValue = right[index];
-    if (leftValue === undefined) return -1;
-    if (rightValue === undefined) return 1;
-    const leftNumeric = /^\d+$/u.test(leftValue);
-    const rightNumeric = /^\d+$/u.test(rightValue);
-    if (leftNumeric && rightNumeric) {
-      const difference = compareNumericIdentifier(leftValue, rightValue);
-      if (difference !== 0) return difference;
-      continue;
+    if (left.length === 0 && right.length === 0)
+        return 0;
+    if (left.length === 0)
+        return 1;
+    if (right.length === 0)
+        return -1;
+    const length = Math.max(left.length, right.length);
+    for (let index = 0; index < length; index += 1) {
+        const leftValue = left[index];
+        const rightValue = right[index];
+        if (leftValue === undefined)
+            return -1;
+        if (rightValue === undefined)
+            return 1;
+        const leftNumeric = /^\d+$/u.test(leftValue);
+        const rightNumeric = /^\d+$/u.test(rightValue);
+        if (leftNumeric && rightNumeric) {
+            const difference = compareNumericIdentifier(leftValue, rightValue);
+            if (difference !== 0)
+                return difference;
+            continue;
+        }
+        if (leftNumeric !== rightNumeric)
+            return leftNumeric ? -1 : 1;
+        if (leftValue < rightValue)
+            return -1;
+        if (leftValue > rightValue)
+            return 1;
     }
-    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
-    if (leftValue < rightValue) return -1;
-    if (leftValue > rightValue) return 1;
-  }
-  return 0;
+    return 0;
 }
-
 export function compareSkillVersions(left, right) {
-  const leftVersion = typeof left === "string" ? parseSkillVersion(left, "left skillVersion") : left;
-  const rightVersion = typeof right === "string" ? parseSkillVersion(right, "right skillVersion") : right;
-  for (let index = 0; index < 3; index += 1) {
-    const difference = compareNumericIdentifier(leftVersion.core[index], rightVersion.core[index]);
-    if (difference !== 0) return difference;
-  }
-  return comparePrerelease(leftVersion.prerelease, rightVersion.prerelease);
+    const leftVersion = typeof left === "string" ? parseSkillVersion(left, "left skillVersion") : left;
+    const rightVersion = typeof right === "string" ? parseSkillVersion(right, "right skillVersion") : right;
+    for (let index = 0; index < 3; index += 1) {
+        const leftIdentifier = leftVersion.core[index];
+        const rightIdentifier = rightVersion.core[index];
+        if (leftIdentifier === undefined || rightIdentifier === undefined) {
+            throw new TypeError("skillVersion core must contain three identifiers");
+        }
+        const difference = compareNumericIdentifier(leftIdentifier, rightIdentifier);
+        if (difference !== 0)
+            return difference;
+    }
+    return comparePrerelease(leftVersion.prerelease, rightVersion.prerelease);
 }
-
 function resolveBundleFile(root, relativePath) {
-  if (typeof relativePath !== "string" || relativePath.trim() === "") {
-    throw new TypeError("skill manifest requiredFiles entries must be non-empty strings");
-  }
-  const segments = relativePath.split("/");
-  if (relativePath !== relativePath.trim()
-    || relativePath.includes("\\")
-    || isAbsolute(relativePath)
-    || segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
-    throw new TypeError(`skill manifest contains unsafe required file ${JSON.stringify(relativePath)}`);
-  }
-  const target = resolve(root, ...segments);
-  const fromRoot = relative(root, target);
-  if (fromRoot === "" || fromRoot === ".." || fromRoot.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`)) {
-    throw new TypeError(`skill manifest required file escapes its bundle: ${relativePath}`);
-  }
-  return target;
+    if (typeof relativePath !== "string" || relativePath.trim() === "") {
+        throw new TypeError("skill manifest requiredFiles entries must be non-empty strings");
+    }
+    const segments = relativePath.split("/");
+    if (relativePath !== relativePath.trim()
+        || relativePath.includes("\\")
+        || isAbsolute(relativePath)
+        || segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+        throw new TypeError(`skill manifest contains unsafe required file ${JSON.stringify(relativePath)}`);
+    }
+    const target = resolve(root, ...segments);
+    const fromRoot = relative(root, target);
+    if (fromRoot === "" || fromRoot === ".." || fromRoot.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`)) {
+        throw new TypeError(`skill manifest required file escapes its bundle: ${relativePath}`);
+    }
+    return target;
 }
-
 function assertRealPathInside(rootRealPath, target, label) {
-  const targetRealPath = realpathSync(target);
-  const fromRoot = relative(rootRealPath, targetRealPath);
-  if (fromRoot === "" || fromRoot === ".." || fromRoot.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`)) {
-    throw new Error(`Odai skill bundle path escapes through a symlink: ${label}`);
-  }
-  return targetRealPath;
+    const targetRealPath = realpathSync(target);
+    const fromRoot = relative(rootRealPath, targetRealPath);
+    if (fromRoot === "" || fromRoot === ".." || fromRoot.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`)) {
+        throw new Error(`Odai skill bundle path escapes through a symlink: ${label}`);
+    }
+    return targetRealPath;
 }
-
 export function readSkillManifest(skillRoot) {
-  const rootRealPath = realpathSync(skillRoot);
-  const manifestPath = resolve(skillRoot, SKILL_MANIFEST_FILE);
-  let parsed;
-  try {
-    const manifestRealPath = assertRealPathInside(rootRealPath, manifestPath, SKILL_MANIFEST_FILE);
-    parsed = JSON.parse(readFileSync(manifestRealPath, "utf8"));
-  } catch (error) {
-    throw new Error(`cannot read Odai skill manifest ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`);
-  }
-  const manifest = assertPlainObject(parsed, `Odai skill manifest ${manifestPath}`);
-  const unknown = Object.keys(manifest).filter((field) => !MANIFEST_FIELDS.has(field));
-  if (unknown.length > 0) {
-    throw new TypeError(`Odai skill manifest ${manifestPath} has unknown fields: ${unknown.join(", ")}`);
-  }
-  if (manifest.schemaVersion !== 1) {
-    throw new TypeError(`Odai skill manifest ${manifestPath} has unsupported schemaVersion ${String(manifest.schemaVersion)}`);
-  }
-  if (manifest.name !== "odai") throw new TypeError(`Odai skill manifest ${manifestPath} must name odai`);
-  const versionParts = parseSkillVersion(manifest.skillVersion, `Odai skill manifest ${manifestPath}.skillVersion`);
-  if (!Number.isSafeInteger(manifest.runtimeContract) || manifest.runtimeContract <= 0) {
-    throw new TypeError(`Odai skill manifest ${manifestPath}.runtimeContract must be a positive integer`);
-  }
-  if (!Array.isArray(manifest.requiredFiles) || manifest.requiredFiles.length === 0) {
-    throw new TypeError(`Odai skill manifest ${manifestPath}.requiredFiles must be a non-empty array`);
-  }
-  const requiredFiles = manifest.requiredFiles.map((file) => {
-    resolveBundleFile(skillRoot, file);
-    return file;
-  });
-  if (new Set(requiredFiles).size !== requiredFiles.length) {
-    throw new TypeError(`Odai skill manifest ${manifestPath}.requiredFiles contains duplicates`);
-  }
-  for (const required of REQUIRED_RUNTIME_FILES) {
-    if (!requiredFiles.includes(required)) {
-      throw new TypeError(`Odai skill manifest ${manifestPath} is missing required runtime file ${required}`);
+    const rootRealPath = realpathSync(skillRoot);
+    const manifestPath = resolve(skillRoot, SKILL_MANIFEST_FILE);
+    let parsed;
+    try {
+        const manifestRealPath = assertRealPathInside(rootRealPath, manifestPath, SKILL_MANIFEST_FILE);
+        parsed = JSON.parse(readFileSync(manifestRealPath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`cannot read Odai skill manifest ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const manifest = assertPlainObject(parsed, `Odai skill manifest ${manifestPath}`);
+    const unknownFields = Object.keys(manifest).filter((field) => !MANIFEST_FIELDS.has(field));
+    if (unknownFields.length > 0) {
+        throw new TypeError(`Odai skill manifest ${manifestPath} has unknown fields: ${unknownFields.join(", ")}`);
+    }
+    if (manifest.schemaVersion !== 1) {
+        throw new TypeError(`Odai skill manifest ${manifestPath} has unsupported schemaVersion ${String(manifest.schemaVersion)}`);
+    }
+    if (manifest.name !== "odai")
+        throw new TypeError(`Odai skill manifest ${manifestPath} must name odai`);
+    if (typeof manifest.skillVersion !== "string") {
+        throw new TypeError(`Odai skill manifest ${manifestPath}.skillVersion must be a string`);
+    }
+    const skillVersion = manifest.skillVersion;
+    const versionParts = parseSkillVersion(skillVersion, `Odai skill manifest ${manifestPath}.skillVersion`);
+    if (typeof manifest.runtimeContract !== "number" || !Number.isSafeInteger(manifest.runtimeContract) || manifest.runtimeContract <= 0) {
+        throw new TypeError(`Odai skill manifest ${manifestPath}.runtimeContract must be a positive integer`);
     }
-  }
-  return Object.freeze({
-    schemaVersion: 1,
-    name: "odai",
-    skillVersion: manifest.skillVersion,
-    versionParts,
-    runtimeContract: manifest.runtimeContract,
-    requiredFiles: Object.freeze(requiredFiles),
-  });
+    if (!Array.isArray(manifest.requiredFiles) || manifest.requiredFiles.length === 0) {
+        throw new TypeError(`Odai skill manifest ${manifestPath}.requiredFiles must be a non-empty array`);
+    }
+    const requiredFiles = manifest.requiredFiles.map((file) => {
+        resolveBundleFile(skillRoot, file);
+        if (typeof file !== "string")
+            throw new TypeError("skill manifest requiredFiles entries must be strings");
+        return file;
+    });
+    if (new Set(requiredFiles).size !== requiredFiles.length) {
+        throw new TypeError(`Odai skill manifest ${manifestPath}.requiredFiles contains duplicates`);
+    }
+    for (const required of REQUIRED_RUNTIME_FILES) {
+        if (!requiredFiles.includes(required)) {
+            throw new TypeError(`Odai skill manifest ${manifestPath} is missing required runtime file ${required}`);
+        }
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        name: "odai",
+        skillVersion,
+        versionParts,
+        runtimeContract: manifest.runtimeContract,
+        requiredFiles: Object.freeze(requiredFiles),
+    });
 }
-
 export function loadSkillBundle(skillPath, options = {}) {
-  const entryPath = resolve(skillPath);
-  const root = dirname(entryPath);
-  const rootRealPath = realpathSync(root);
-  const manifest = readSkillManifest(root);
-  const digest = createHash("sha256");
-  const contents = new Map();
-  digest.update(JSON.stringify({
-    schemaVersion: manifest.schemaVersion,
-    name: manifest.name,
-    skillVersion: manifest.skillVersion,
-    runtimeContract: manifest.runtimeContract,
-    requiredFiles: manifest.requiredFiles,
-  }));
-
-  for (const relativePath of [...manifest.requiredFiles].sort()) {
-    const path = resolveBundleFile(root, relativePath);
-    if (!existsSync(path)) throw new Error(`Odai skill bundle ${root} is missing ${relativePath}`);
-    const realPath = assertRealPathInside(rootRealPath, path, relativePath);
-    const content = readFileSync(realPath);
-    contents.set(relativePath, content);
-    digest.update("\0");
-    digest.update(relativePath);
-    digest.update("\0");
-    digest.update(content);
-  }
-
-  const skillText = contents.get("SKILL.md").toString("utf8").trim();
-  if (!skillText) throw new Error(`Odai canonical skill is empty: ${entryPath}`);
-  const frontmatter = skillText.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u)?.[1];
-  if (!frontmatter || !/^name:\s*odai\s*$/mu.test(frontmatter)) {
-    throw new Error(`Odai canonical skill entry does not declare name odai: ${entryPath}`);
-  }
-
-  const roleContracts = Object.freeze(Object.fromEntries(["controller", "researcher", "planner", "executor", "reviewer", "frontend"].map((role) => {
-    const relativePath = `assets/routing-roles/${role}.md`;
-    const text = contents.get(relativePath).toString("utf8").trim();
-    if (!text) throw new Error(`Odai canonical ${role} role is unavailable: ${resolve(root, relativePath)}`);
-    return [role, text];
-  })));
-  const referenceContracts = Object.freeze(Object.fromEntries(["craft"].map((reference) => {
-    const relativePath = `references/${reference}.md`;
-    const text = contents.get(relativePath)?.toString("utf8").trim();
-    if (!text) throw new Error(`Odai canonical ${reference} reference is unavailable: ${resolve(root, relativePath)}`);
-    return [reference, text];
-  })));
-  const fileContents = Object.freeze(Object.fromEntries(
-    [...contents].map(([relativePath, content]) => [relativePath, content.toString("base64")]),
-  ));
-
-  const bundle = {
-    path: entryPath,
-    root,
-    source: typeof options.source === "string" && options.source ? options.source : "bundled",
-    provider: typeof options.provider === "string" && options.provider ? options.provider : "odai-dsh-runtime",
-    manifest,
-    skillText,
-    roleContracts,
-    referenceContracts,
-    digest: digest.digest("hex"),
-  };
-  Object.defineProperty(bundle, "fileContents", { value: fileContents, enumerable: false });
-  return Object.freeze(bundle);
+    const entryPath = resolve(skillPath);
+    const root = dirname(entryPath);
+    const rootRealPath = realpathSync(root);
+    const manifest = readSkillManifest(root);
+    const digest = createHash("sha256");
+    const contents = new Map();
+    digest.update(JSON.stringify({
+        schemaVersion: manifest.schemaVersion,
+        name: manifest.name,
+        skillVersion: manifest.skillVersion,
+        runtimeContract: manifest.runtimeContract,
+        requiredFiles: manifest.requiredFiles,
+    }));
+    for (const relativePath of [...manifest.requiredFiles].sort()) {
+        const path = resolveBundleFile(root, relativePath);
+        if (!existsSync(path))
+            throw new Error(`Odai skill bundle ${root} is missing ${relativePath}`);
+        const realPath = assertRealPathInside(rootRealPath, path, relativePath);
+        const content = readFileSync(realPath);
+        contents.set(relativePath, content);
+        digest.update("\0");
+        digest.update(relativePath);
+        digest.update("\0");
+        digest.update(content);
+    }
+    const skillContent = contents.get("SKILL.md");
+    if (!skillContent)
+        throw new Error(`Odai skill bundle ${root} is missing SKILL.md`);
+    const skillText = skillContent.toString("utf8").trim();
+    if (!skillText)
+        throw new Error(`Odai canonical skill is empty: ${entryPath}`);
+    const frontmatter = skillText.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u)?.[1];
+    if (!frontmatter || !/^name:\s*odai\s*$/mu.test(frontmatter)) {
+        throw new Error(`Odai canonical skill entry does not declare name odai: ${entryPath}`);
+    }
+    const roleContracts = Object.freeze(Object.fromEntries(["controller", "researcher", "planner", "executor", "reviewer", "frontend"].map((role) => {
+        const relativePath = `assets/routing-roles/${role}.md`;
+        const content = contents.get(relativePath);
+        if (!content)
+            throw new Error(`Odai canonical ${role} role is unavailable: ${resolve(root, relativePath)}`);
+        const text = content.toString("utf8").trim();
+        if (!text)
+            throw new Error(`Odai canonical ${role} role is unavailable: ${resolve(root, relativePath)}`);
+        return [role, text];
+    })));
+    const referenceContracts = Object.freeze(Object.fromEntries(["craft"].map((reference) => {
+        const relativePath = `references/${reference}.md`;
+        const text = contents.get(relativePath)?.toString("utf8").trim();
+        if (!text)
+            throw new Error(`Odai canonical ${reference} reference is unavailable: ${resolve(root, relativePath)}`);
+        return [reference, text];
+    })));
+    const fileContents = Object.freeze(Object.fromEntries([...contents].map(([relativePath, content]) => [relativePath, content.toString("base64")])));
+    const bundle = {
+        path: entryPath,
+        root,
+        source: typeof options.source === "string" && options.source ? options.source : "bundled",
+        provider: typeof options.provider === "string" && options.provider ? options.provider : "odai-dsh-runtime",
+        manifest,
+        skillText,
+        roleContracts,
+        referenceContracts,
+        digest: digest.digest("hex"),
+        fileContents,
+    };
+    Object.defineProperty(bundle, "fileContents", { value: fileContents, enumerable: false });
+    return Object.freeze(bundle);
 }
-
 export function readSkillBundleFile(bundle, relativePath) {
-  if (!bundle || typeof bundle !== "object" || !bundle.manifest?.requiredFiles?.includes(relativePath)) {
-    throw new TypeError(`unknown Odai skill bundle file: ${String(relativePath)}`);
-  }
-  const encoded = bundle.fileContents?.[relativePath];
-  if (typeof encoded !== "string") throw new Error(`Odai skill bundle snapshot is missing ${relativePath}`);
-  return Buffer.from(encoded, "base64");
+    if (!bundle || typeof bundle !== "object" || !bundle.manifest?.requiredFiles?.includes(relativePath)) {
+        throw new TypeError(`unknown Odai skill bundle file: ${String(relativePath)}`);
+    }
+    const encoded = bundle.fileContents?.[relativePath];
+    if (typeof encoded !== "string")
+        throw new Error(`Odai skill bundle snapshot is missing ${relativePath}`);
+    return Buffer.from(encoded, "base64");
 }
-
 function fallbackSelection(mode, bundled, reasonCode, detail, candidate) {
-  return Object.freeze({
-    mode,
-    status: "fallback",
-    reasonCode,
-    detail,
-    bundle: bundled,
-    ...(candidate ? { candidate } : {}),
-  });
+    return Object.freeze({
+        mode,
+        status: "fallback",
+        reasonCode,
+        ...(detail === undefined ? {} : { detail }),
+        bundle: bundled,
+        ...(candidate ? { candidate } : {}),
+    });
 }
-
 function selected(mode, bundle, reasonCode, candidate) {
-  return Object.freeze({
-    mode,
-    status: "selected",
-    reasonCode,
-    bundle,
-    ...(candidate ? { candidate } : {}),
-  });
+    return Object.freeze({
+        mode,
+        status: "selected",
+        reasonCode,
+        bundle,
+        ...(candidate ? { candidate } : {}),
+    });
 }
-
-export function chooseSkillBundle({ mode, bundled, candidate, candidateError } = {}) {
-  if (!SKILL_SOURCE_MODES.includes(mode)) throw new TypeError(`unknown Odai skill source mode: ${String(mode)}`);
-  if (!bundled) throw new TypeError("bundled Odai skill is required");
-  if (mode === "bundled") return selected(mode, bundled, "bundled-configured");
-  if (candidateError) {
-    return fallbackSelection(mode, bundled, "external-invalid", candidateError instanceof Error ? candidateError.message : String(candidateError));
-  }
-  if (!candidate) {
-    return mode === "auto"
-      ? selected(mode, bundled, "external-not-installed")
-      : fallbackSelection(mode, bundled, "user-source-missing", "no compatible user-level Odai skill is installed");
-  }
-  if (candidate.manifest.runtimeContract !== ODAI_RUNTIME_CONTRACT) {
-    return fallbackSelection(
-      mode,
-      bundled,
-      "runtime-contract-mismatch",
-      `candidate runtimeContract ${candidate.manifest.runtimeContract} is incompatible with runtime contract ${ODAI_RUNTIME_CONTRACT}`,
-      candidate,
-    );
-  }
-
-  const versionOrder = compareSkillVersions(candidate.manifest.versionParts, bundled.manifest.versionParts);
-  if (versionOrder === 0) {
-    if (candidate.digest === bundled.digest) return selected(mode, bundled, "external-equivalent", candidate);
-    return fallbackSelection(
-      mode,
-      bundled,
-      "same-version-content-conflict",
-      `candidate ${candidate.manifest.skillVersion} differs from the bundled content with the same version`,
-      candidate,
-    );
-  }
-
-  if (mode === "user") {
-    if (!USER_SOURCES.has(candidate.source) && candidate.source !== "custom") {
-      return fallbackSelection(mode, bundled, "user-source-invalid", `source ${candidate.source} is not user-level`, candidate);
+export function chooseSkillBundle(options = {}) {
+    const { mode, bundled, candidate, candidateError } = options;
+    if (!isSkillSourceMode(mode))
+        throw new TypeError(`unknown Odai skill source mode: ${String(mode)}`);
+    if (!bundled)
+        throw new TypeError("bundled Odai skill is required");
+    if (mode === "bundled")
+        return selected(mode, bundled, "bundled-configured");
+    if (candidateError) {
+        return fallbackSelection(mode, bundled, "external-invalid", candidateError instanceof Error ? candidateError.message : String(candidateError));
+    }
+    if (!candidate) {
+        return mode === "auto"
+            ? selected(mode, bundled, "external-not-installed")
+            : fallbackSelection(mode, bundled, "user-source-missing", "no compatible user-level Odai skill is installed");
+    }
+    if (candidate.manifest.runtimeContract !== ODAI_RUNTIME_CONTRACT) {
+        return fallbackSelection(mode, bundled, "runtime-contract-mismatch", `candidate runtimeContract ${candidate.manifest.runtimeContract} is incompatible with runtime contract ${ODAI_RUNTIME_CONTRACT}`, candidate);
+    }
+    const versionOrder = compareSkillVersions(candidate.manifest.versionParts, bundled.manifest.versionParts);
+    if (versionOrder === 0) {
+        if (candidate.digest === bundled.digest)
+            return selected(mode, bundled, "external-equivalent", candidate);
+        return fallbackSelection(mode, bundled, "same-version-content-conflict", `candidate ${candidate.manifest.skillVersion} differs from the bundled content with the same version`, candidate);
+    }
+    if (mode === "user") {
+        if (!USER_SOURCES.has(candidate.source) && candidate.source !== "custom") {
+            return fallbackSelection(mode, bundled, "user-source-invalid", `source ${candidate.source} is not user-level`, candidate);
+        }
+        return selected(mode, candidate, "user-configured", candidate);
+    }
+    if (PROJECT_SOURCES.has(candidate.source))
+        return selected(mode, candidate, "project-scope-override", candidate);
+    if (USER_SOURCES.has(candidate.source)) {
+        return versionOrder > 0
+            ? selected(mode, candidate, "newer-user-skill", candidate)
+            : fallbackSelection(mode, bundled, "user-skill-older", `candidate ${candidate.manifest.skillVersion} is older than bundled ${bundled.manifest.skillVersion}`, candidate);
     }
-    return selected(mode, candidate, "user-configured", candidate);
-  }
-  if (PROJECT_SOURCES.has(candidate.source)) return selected(mode, candidate, "project-scope-override", candidate);
-  if (USER_SOURCES.has(candidate.source)) {
-    return versionOrder > 0
-      ? selected(mode, candidate, "newer-user-skill", candidate)
-      : fallbackSelection(
-          mode,
-          bundled,
-          "user-skill-older",
-          `candidate ${candidate.manifest.skillVersion} is older than bundled ${bundled.manifest.skillVersion}`,
-          candidate,
-        );
-  }
-  return fallbackSelection(mode, bundled, "external-source-unsupported", `source ${candidate.source} cannot provide Odai governance`, candidate);
+    return fallbackSelection(mode, bundled, "external-source-unsupported", `source ${candidate.source} cannot provide Odai governance`, candidate);
 }
+//# sourceMappingURL=skill-bundle.mjs.map