@sellable/install 0.1.578 → 0.1.581

package/lib/sellable-agent/fly-skills-bridge.mjs

@@ -0,0 +1,977 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+
+import {
+  SOUL_BRIDGE_DATA_ROOT,
+  discoverLiveHermesGateway,
+  revalidateLiveHermesGateway,
+  soulProfilePaths,
+  withProfileSoulLock,
+} from "./fly-soul-bridge.mjs";
+import { markHermesSnapshotDirty } from "./hermes-memory-snapshot.mjs";
+
+export const SKILLS_BRIDGE_SCHEMA_VERSION = "sellable-agent-skills-bridge/v1";
+export const SKILLS_PROOF_SCHEMA_VERSION = "sellable-agent-skills-proof/v1";
+export const SKILLS_MAX_COUNT = 256;
+export const SKILL_MAX_FILES = 256;
+export const SKILL_MAX_TOTAL_BYTES = 2 * 1024 * 1024;
+export const SKILL_MAX_TEXT_BYTES = 256 * 1024;
+export const SKILLS_REQUEST_MAX_BYTES = 512 * 1024;
+
+const PROFILE_ID = /^[a-z0-9][a-z0-9_-]{0,127}$/;
+const SHA256 = /^[a-f0-9]{64}$/;
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const PYTHON = "/opt/hermes/.venv/bin/python3";
+const SUPPORT_ROOTS = new Set(["references", "templates"]);
+const SOURCE_MANAGED = new Set(["bundled", "hub", "plugin", "org", "external"]);
+
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+const stableJson = (value) => {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+};
+
+export class FlySkillsBridgeError extends Error {
+  constructor(code) {
+    super(code);
+    this.name = "FlySkillsBridgeError";
+    this.code = code;
+  }
+}
+
+function fail(code) {
+  throw new FlySkillsBridgeError(code);
+}
+
+function validProfileId(value) {
+  if (typeof value !== "string" || !PROFILE_ID.test(value)) {
+    fail("skills_profile_id_rejected");
+  }
+  return value;
+}
+
+function utf8(bytes, code = "skills_utf8_rejected") {
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    fail(code);
+  }
+}
+
+function safeRelativePath(value, { supporting = false } = {}) {
+  if (
+    typeof value !== "string" ||
+    value.length < 1 ||
+    value.length > 256 ||
+    value.includes("\\") ||
+    value.includes("\0") ||
+    isAbsolute(value)
+  ) {
+    fail("skills_file_path_rejected");
+  }
+  const parts = value.split("/");
+  if (parts.some((part) => !part || part === "." || part === "..")) {
+    fail("skills_file_path_rejected");
+  }
+  if (supporting && (!SUPPORT_ROOTS.has(parts[0]) || parts.length < 2)) {
+    fail("skills_support_path_rejected");
+  }
+  return parts.join("/");
+}
+
+function regularFile(path, maxBytes = SKILL_MAX_TOTAL_BYTES) {
+  const link = lstatSync(path);
+  if (
+    link.isSymbolicLink() ||
+    !link.isFile() ||
+    link.nlink !== 1 ||
+    link.size > maxBytes
+  ) {
+    fail("skills_file_rejected");
+  }
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const opened = fstatSync(fd);
+    if (
+      !opened.isFile() ||
+      opened.dev !== link.dev ||
+      opened.ino !== link.ino ||
+      opened.nlink !== 1 ||
+      opened.size !== link.size
+    ) {
+      fail("skills_file_changed");
+    }
+    return readFileSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function contained(root, candidate) {
+  const rel = relative(root, candidate);
+  return (
+    rel !== "" &&
+    rel !== ".." &&
+    !rel.startsWith(`..${sep}`) &&
+    !isAbsolute(rel)
+  );
+}
+
+function inspectTree(skillRoot, limits) {
+  const entries = [];
+  let totalBytes = 0;
+  let incompleteReason = null;
+  const walk = (directory) => {
+    for (const name of readdirSync(directory).sort()) {
+      const path = join(directory, name);
+      const link = lstatSync(path);
+      if (link.isSymbolicLink()) {
+        incompleteReason ??= "symlink";
+        continue;
+      }
+      if (link.isDirectory()) {
+        walk(path);
+        continue;
+      }
+      if (!link.isFile() || link.nlink !== 1) {
+        incompleteReason ??= "non_regular";
+        continue;
+      }
+      if (entries.length >= limits.maxFiles) {
+        incompleteReason ??= "file_count";
+        continue;
+      }
+      if (totalBytes + link.size > limits.maxTotalBytes) {
+        incompleteReason ??= "total_bytes";
+        continue;
+      }
+      const bytes = regularFile(path, limits.maxTotalBytes);
+      totalBytes += bytes.byteLength;
+      entries.push({
+        relativePath: relative(skillRoot, path).split(sep).join("/"),
+        byteLength: bytes.byteLength,
+        fileSha256: sha256(bytes),
+      });
+    }
+  };
+  walk(skillRoot);
+  return { entries, totalBytes, incompleteReason };
+}
+
+function normalizedProvenance(item, editable) {
+  const upstream = String(
+    item.provenance ?? item.source ?? "unknown"
+  ).toLowerCase();
+  if (!editable) {
+    if (String(item.name).toLowerCase() === "sellable") return "sellable";
+    return SOURCE_MANAGED.has(upstream) ? upstream : "external";
+  }
+  return "profile";
+}
+
+function skillId(item, provenance, relativeDirectory) {
+  return sha256(
+    stableJson({
+      name: String(item.name),
+      provenance,
+      relativeDirectory,
+    })
+  );
+}
+
+function disabledBytes(native) {
+  if (typeof native.disabledConfig === "string") {
+    return Buffer.from(native.disabledConfig, "utf8");
+  }
+  return Buffer.from(
+    `${stableJson([...new Set(native.disabledNames ?? [])].sort())}\n`,
+    "utf8"
+  );
+}
+
+function normalizeEnumeration(native, paths, limits = {}) {
+  const maxSkills = limits.maxSkills ?? SKILLS_MAX_COUNT;
+  const treeLimits = {
+    maxFiles: limits.maxFiles ?? SKILL_MAX_FILES,
+    maxTotalBytes: limits.maxTotalBytes ?? SKILL_MAX_TOTAL_BYTES,
+  };
+  if (
+    !native ||
+    !Array.isArray(native.skills) ||
+    !Array.isArray(native.disabledNames)
+  ) {
+    fail("skills_native_enumeration_rejected");
+  }
+  const disabled = new Set(native.disabledNames.map(String));
+  const profileSkillsRoot = join(paths.profileRoot, "skills");
+  const canonicalProfileSkillsRoot = existsSync(profileSkillsRoot)
+    ? realpathSync(profileSkillsRoot)
+    : profileSkillsRoot;
+  const skills = [];
+  let incompleteReason =
+    native.complete === false ? String(native.reason ?? "native") : null;
+  for (const item of native.skills.slice(0, maxSkills)) {
+    if (
+      !item ||
+      !SAFE_NAME.test(String(item.name ?? "")) ||
+      typeof item.path !== "string"
+    ) {
+      incompleteReason ??= "native_entry";
+      continue;
+    }
+    let canonicalRoot;
+    try {
+      const link = lstatSync(item.path);
+      if (link.isSymbolicLink() || !link.isDirectory()) {
+        incompleteReason ??= "symlink";
+        continue;
+      }
+      canonicalRoot = realpathSync(item.path);
+    } catch {
+      incompleteReason ??= "missing";
+      continue;
+    }
+    const relativeDirectory = contained(
+      canonicalProfileSkillsRoot,
+      canonicalRoot
+    )
+      ? relative(canonicalProfileSkillsRoot, canonicalRoot).split(sep).join("/")
+      : null;
+    const upstream = String(
+      item.provenance ?? item.source ?? "unknown"
+    ).toLowerCase();
+    const editable = Boolean(
+      relativeDirectory &&
+        !relativeDirectory.split("/").includes(".org") &&
+        !SOURCE_MANAGED.has(upstream) &&
+        String(item.name).toLowerCase() !== "sellable"
+    );
+    const provenance = normalizedProvenance(item, editable);
+    const tree = inspectTree(canonicalRoot, treeLimits);
+    incompleteReason ??= tree.incompleteReason;
+    const skillMd = tree.entries.find(
+      (entry) => entry.relativePath === "SKILL.md"
+    );
+    if (!skillMd) {
+      incompleteReason ??= "manifest_missing";
+      continue;
+    }
+    let manifestContent = null;
+    if (skillMd.byteLength <= SKILL_MAX_TEXT_BYTES) {
+      try {
+        manifestContent = utf8(
+          regularFile(join(canonicalRoot, "SKILL.md"), SKILL_MAX_TEXT_BYTES)
+        );
+      } catch {
+        incompleteReason ??= "manifest_utf8";
+      }
+    } else {
+      incompleteReason ??= "manifest_bytes";
+    }
+    const manifestIdentity = {
+      provenance,
+      relativeDirectory,
+      entries: tree.entries,
+    };
+    skills.push({
+      skillId: skillId(item, provenance, relativeDirectory),
+      name: String(item.name),
+      description: String(item.description ?? "").slice(0, 2000),
+      category:
+        item.category == null ? null : String(item.category).slice(0, 128),
+      provenance,
+      editable,
+      enabled: !disabled.has(String(item.name)),
+      usage:
+        Number.isSafeInteger(item.usage) && item.usage >= 0 ? item.usage : 0,
+      manifestContent,
+      fileSha256: skillMd.fileSha256,
+      skillManifestSha256: sha256(stableJson(manifestIdentity)),
+      manifest: tree.entries,
+      _canonicalRoot: canonicalRoot,
+    });
+  }
+  if (native.skills.length > maxSkills) incompleteReason ??= "skill_count";
+  skills.sort((left, right) => left.skillId.localeCompare(right.skillId));
+  const disabledConfigSha256 = sha256(disabledBytes(native));
+  const inventorySha256 = sha256(
+    stableJson(
+      skills.map(
+        ({ _canonicalRoot: _private, manifestContent: _content, ...skill }) =>
+          skill
+      )
+    )
+  );
+  return {
+    complete: incompleteReason === null,
+    ...(incompleteReason === null
+      ? {}
+      : {
+          code: "inventory_incomplete",
+          truncation: {
+            reason: incompleteReason,
+            observedSkillCount: native.skills.length,
+            returnedSkillCount: skills.length,
+          },
+        }),
+    disabledConfigSha256,
+    inventorySha256,
+    skills,
+  };
+}
+
+function publicInventory(inventory) {
+  return {
+    ...inventory,
+    skills: inventory.skills.map(({ _canonicalRoot, ...skill }) => skill),
+  };
+}
+
+const NATIVE_SCRIPT = String.raw`
+import json, os, sys
+request = json.loads(sys.stdin.read())
+from tools.skills_tool import _find_all_skills, skill_view
+from tools.skill_manager_tool import _find_skill, _create_skill, _edit_skill, _delete_skill, _write_file, _remove_file
+from hermes_cli.config import load_config
+from hermes_cli.skills_config import get_disabled_skills, save_disabled_skills
+
+def inventory(read_name=None, read_file=None):
+    rows = _find_all_skills(skip_disabled=True)
+    config = load_config()
+    disabled = sorted(get_disabled_skills(config))
+    result = []
+    try:
+        from tools.skill_usage import _read_bundled_manifest_names, _read_hub_installed_names, activity_count, load_usage
+        bundled, hub, usage = _read_bundled_manifest_names(), _read_hub_installed_names(), load_usage()
+    except Exception:
+        bundled, hub, usage = set(), set(), {}
+    for row in rows:
+        name = str(row.get("name") or "")
+        found = _find_skill(name)
+        if not found:
+            continue
+        provenance = "hub" if name in hub else "bundled" if name in bundled else "agent"
+        item = dict(row)
+        item.update({"path": str(found["path"]), "provenance": provenance, "usage": activity_count(usage.get(name, {})) if usage else 0})
+        result.append(item)
+    viewed = None
+    if read_name:
+        viewed = skill_view(read_name, file_path=read_file) if read_file else skill_view(read_name)
+    return {"complete": True, "skills": result, "disabledNames": disabled, "disabledConfig": json.dumps(disabled, separators=(",", ":")), "nativeView": viewed}
+
+op = request.get("operation")
+if op == "enumerate":
+    output = inventory(request.get("readName"), request.get("readFile"))
+elif op == "read":
+    output = {"nativeView": skill_view(request["readName"], file_path=request.get("readFile")) if request.get("readFile") else skill_view(request["readName"])}
+elif op == "scan":
+    from tools.skills_guard import scan_skill, should_allow_install
+    path = request["path"]
+    scan = scan_skill(path, source="agent-created")
+    allowed, reason = should_allow_install(scan)
+    output = {"ok": allowed is True, "reason": str(reason)}
+elif op == "mutate":
+    action = request["action"]
+    name = request["name"]
+    if action == "create": output = _create_skill(name, request["content"], request.get("category"))
+    elif action == "edit": output = _edit_skill(name, request["content"])
+    elif action == "delete": output = _delete_skill(name, "")
+    elif action == "write_file": output = _write_file(name, request["filePath"], request["content"])
+    elif action == "remove_file": output = _remove_file(name, request["filePath"])
+    elif action == "toggle":
+        config = load_config(); disabled = get_disabled_skills(config)
+        if request["enabled"]: disabled.discard(name)
+        else: disabled.add(name)
+        save_disabled_skills(config, disabled)
+        output = {"success": True}
+    else: raise RuntimeError("operation")
+else:
+    raise RuntimeError("operation")
+sys.stdout.write(json.dumps(output, separators=(",", ":")))
+`;
+
+function runNative(payload, paths, { python = PYTHON } = {}) {
+  const child = spawnSync(python, ["-c", NATIVE_SCRIPT], {
+    input: JSON.stringify(payload),
+    encoding: "utf8",
+    timeout: 20_000,
+    maxBuffer: 4 * 1024 * 1024,
+    env: {
+      HOME: paths.dataRoot,
+      HERMES_HOME: paths.profileRoot,
+      HERMES_PROFILE: paths.profileId,
+      SELLABLE_HERMES_PROFILE_ID: paths.profileId,
+      SELLABLE_AGENT_RUNTIME: "1",
+      PYTHONDONTWRITEBYTECODE: "1",
+      PATH: "/opt/hermes/.venv/bin:/usr/local/bin:/usr/bin:/bin",
+    },
+  });
+  if (child.status !== 0 || child.signal || child.error)
+    fail("skills_native_call_failed");
+  try {
+    return JSON.parse(child.stdout);
+  } catch {
+    fail("skills_native_output_rejected");
+  }
+}
+
+function defaultAdapter(paths) {
+  return {
+    enumerate: ({ readName, readFile } = {}) =>
+      runNative({ operation: "enumerate", readName, readFile }, paths),
+    read: ({ readName, readFile } = {}) =>
+      runNative({ operation: "read", readName, readFile }, paths),
+    scan: (path) => runNative({ operation: "scan", path }, paths),
+    mutate: (mutation) =>
+      runNative({ operation: "mutate", ...mutation }, paths),
+  };
+}
+
+function assertExactKeys(value, allowed) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    fail("skills_request_rejected");
+  if (Object.keys(value).some((key) => !allowed.has(key)))
+    fail("skills_request_rejected");
+}
+
+function assertRequest(request) {
+  const common = ["operation"];
+  const shapes = {
+    list: common,
+    read: [...common, "skillId", "filePath"],
+    edit: [...common, "skillId", "content", "expectedFileSha256"],
+    toggle: [...common, "skillId", "enabled", "disabledConfigSha256"],
+    create: [
+      ...common,
+      "name",
+      "content",
+      "category",
+      "expectedFileAbsent",
+      "inventorySha256",
+    ],
+    delete: [...common, "skillId", "skillManifestSha256"],
+    write_file: [
+      ...common,
+      "skillId",
+      "filePath",
+      "content",
+      "expectedFileSha256",
+      "expectedFileAbsent",
+      "skillManifestSha256",
+    ],
+    remove_file: [
+      ...common,
+      "skillId",
+      "filePath",
+      "expectedFileSha256",
+      "skillManifestSha256",
+    ],
+  };
+  const keys = shapes[request?.operation];
+  if (!keys) fail("skills_operation_rejected");
+  assertExactKeys(request, new Set(keys));
+  if (
+    request.operation === "create" &&
+    (!SAFE_NAME.test(request.name ?? "") ||
+      (request.category != null && !SAFE_NAME.test(request.category)))
+  ) {
+    fail("skills_category_rejected");
+  }
+  if (request.skillId !== undefined && !SHA256.test(request.skillId))
+    fail("skills_identity_rejected");
+  if (request.content !== undefined) {
+    if (
+      typeof request.content !== "string" ||
+      Buffer.byteLength(request.content) > SKILL_MAX_TEXT_BYTES
+    ) {
+      fail("skills_content_rejected");
+    }
+  }
+  if (request.filePath !== undefined)
+    safeRelativePath(request.filePath, {
+      supporting: request.operation !== "read",
+    });
+  for (const field of [
+    "expectedFileSha256",
+    "disabledConfigSha256",
+    "inventorySha256",
+    "skillManifestSha256",
+  ]) {
+    if (request[field] !== undefined && !SHA256.test(request[field]))
+      fail("skills_cas_rejected");
+  }
+  return request;
+}
+
+function findSkill(inventory, id, { editable = false } = {}) {
+  const skill = inventory.skills.find((entry) => entry.skillId === id);
+  if (!skill) fail("skills_identity_not_found");
+  if (editable && (!inventory.complete || !skill.editable))
+    fail("skills_mutation_refused");
+  return skill;
+}
+
+function backupTree(skillRoot) {
+  const snapshot = [];
+  const walk = (directory) => {
+    for (const name of readdirSync(directory).sort()) {
+      const path = join(directory, name);
+      const stat = lstatSync(path);
+      if (stat.isSymbolicLink()) fail("skills_backup_rejected");
+      if (stat.isDirectory()) walk(path);
+      else if (stat.isFile())
+        snapshot.push({
+          relativePath: relative(skillRoot, path),
+          bytes: regularFile(path),
+          mode: stat.mode & 0o777,
+        });
+      else fail("skills_backup_rejected");
+    }
+  };
+  walk(skillRoot);
+  return snapshot;
+}
+
+function restoreTree(skillRoot, snapshot) {
+  rmSync(skillRoot, { recursive: true, force: true });
+  mkdirSync(skillRoot, { recursive: true, mode: 0o700 });
+  for (const entry of snapshot) {
+    const path = join(skillRoot, entry.relativePath);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, entry.bytes, { mode: entry.mode });
+  }
+}
+
+function atomicProof(paths, inventory) {
+  const root = join(paths.profileRoot, ".sellable-agent");
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+  const path = join(root, "skills-proof.json");
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  const value = {
+    schemaVersion: SKILLS_PROOF_SCHEMA_VERSION,
+    inventorySha256: inventory.inventorySha256,
+    disabledConfigSha256: inventory.disabledConfigSha256,
+  };
+  writeFileSync(temporary, `${JSON.stringify(value)}\n`, { mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+function executeLocked(request, paths, adapter, options) {
+  const beforeNative = adapter.enumerate();
+  const before = normalizeEnumeration(beforeNative, paths, options.limits);
+  if (request.operation === "list") {
+    atomicProof(paths, before);
+    return {
+      ok: true,
+      schemaVersion: SKILLS_BRIDGE_SCHEMA_VERSION,
+      status: "proven",
+      ...publicInventory(before),
+    };
+  }
+  if (request.operation === "read") {
+    const skill = findSkill(before, request.skillId);
+    const relativePath = request.filePath
+      ? safeRelativePath(request.filePath)
+      : "SKILL.md";
+    const manifest = skill.manifest.find(
+      (entry) => entry.relativePath === relativePath
+    );
+    if (!manifest)
+      return {
+        ok: false,
+        code: before.complete
+          ? "skills_file_not_found"
+          : "inventory_incomplete",
+      };
+    if (manifest.byteLength > SKILL_MAX_TEXT_BYTES)
+      return { ok: false, code: "skills_file_too_large" };
+    const content = utf8(
+      regularFile(
+        join(skill._canonicalRoot, relativePath),
+        SKILL_MAX_TEXT_BYTES
+      )
+    );
+    const proof = adapter.read({
+      readName: skill.name,
+      readFile: relativePath === "SKILL.md" ? undefined : relativePath,
+    });
+    if (typeof proof.nativeView !== "string")
+      fail("skills_native_readback_failed");
+    atomicProof(paths, before);
+    return {
+      ok: true,
+      schemaVersion: SKILLS_BRIDGE_SCHEMA_VERSION,
+      status: "proven",
+      skill: publicInventory({ ...before, skills: [skill] }).skills[0],
+      filePath: relativePath,
+      content,
+      fileSha256: sha256(Buffer.from(content, "utf8")),
+      inventorySha256: before.inventorySha256,
+      disabledConfigSha256: before.disabledConfigSha256,
+    };
+  }
+
+  if (!before.complete)
+    return {
+      ok: false,
+      code: "inventory_incomplete",
+      inventorySha256: before.inventorySha256,
+    };
+  let skill =
+    request.operation === "create"
+      ? null
+      : findSkill(before, request.skillId, { editable: true });
+  if (request.operation === "create") {
+    if (
+      !SAFE_NAME.test(request.name ?? "") ||
+      request.expectedFileAbsent !== true ||
+      request.inventorySha256 !== before.inventorySha256
+    ) {
+      return {
+        ok: false,
+        code: "skills_conflict",
+        inventorySha256: before.inventorySha256,
+      };
+    }
+    if (before.skills.some((entry) => entry.name === request.name))
+      return { ok: false, code: "skills_absent_conflict" };
+  }
+  if (
+    request.operation === "edit" &&
+    request.expectedFileSha256 !== skill.fileSha256
+  )
+    return {
+      ok: false,
+      code: "skills_file_conflict",
+      fileSha256: skill.fileSha256,
+    };
+  if (
+    request.operation === "toggle" &&
+    request.disabledConfigSha256 !== before.disabledConfigSha256
+  )
+    return {
+      ok: false,
+      code: "skills_disabled_config_conflict",
+      disabledConfigSha256: before.disabledConfigSha256,
+    };
+  if (
+    ["delete", "write_file", "remove_file"].includes(request.operation) &&
+    request.skillManifestSha256 !== skill.skillManifestSha256
+  )
+    return {
+      ok: false,
+      code: "skills_manifest_conflict",
+      skillManifestSha256: skill.skillManifestSha256,
+    };
+  let supportingExisting = null;
+  if (["write_file", "remove_file"].includes(request.operation)) {
+    const relativePath = safeRelativePath(request.filePath, {
+      supporting: true,
+    });
+    supportingExisting =
+      skill.manifest.find((entry) => entry.relativePath === relativePath) ??
+      null;
+    if (request.operation === "remove_file" || supportingExisting) {
+      if (
+        !supportingExisting ||
+        request.expectedFileSha256 !== supportingExisting.fileSha256
+      )
+        return {
+          ok: false,
+          code: "skills_file_conflict",
+          fileSha256: supportingExisting?.fileSha256 ?? null,
+        };
+    } else if (request.expectedFileAbsent !== true)
+      return { ok: false, code: "skills_absent_conflict" };
+  }
+
+  const skillRoot =
+    skill?._canonicalRoot ??
+    join(
+      paths.profileRoot,
+      "skills",
+      request.category ? join(request.category, request.name) : request.name
+    );
+  const skillExisted = existsSync(skillRoot);
+  const treeBackup = skillExisted ? backupTree(skillRoot) : [];
+  const disabledPath = join(paths.profileRoot, "config.yaml");
+  const disabledBackup = existsSync(disabledPath)
+    ? regularFile(disabledPath)
+    : null;
+  const proofPath = join(
+    paths.profileRoot,
+    ".sellable-agent",
+    "skills-proof.json"
+  );
+  const proofBackup = existsSync(proofPath)
+    ? regularFile(proofPath, 4096)
+    : null;
+  const rollback = () => {
+    if (skillExisted) restoreTree(skillRoot, treeBackup);
+    else rmSync(skillRoot, { recursive: true, force: true });
+    if (disabledBackup !== null)
+      writeFileSync(disabledPath, disabledBackup, { mode: 0o600 });
+    if (proofBackup !== null)
+      writeFileSync(proofPath, proofBackup, { mode: 0o600 });
+    else rmSync(proofPath, { force: true });
+  };
+  try {
+    const scanTarget = skillRoot;
+    if (skillExisted) {
+      const scan = adapter.scan(scanTarget);
+      if (scan?.ok !== true) fail("skills_scan_refused");
+    }
+    const noEffect =
+      (request.operation === "edit" &&
+        sha256(Buffer.from(request.content, "utf8")) === skill.fileSha256) ||
+      (request.operation === "toggle" && request.enabled === skill.enabled) ||
+      (request.operation === "write_file" &&
+        supportingExisting !== null &&
+        sha256(Buffer.from(request.content, "utf8")) ===
+          supportingExisting.fileSha256);
+    if (noEffect) {
+      atomicProof(paths, before);
+      return {
+        ok: true,
+        schemaVersion: SKILLS_BRIDGE_SCHEMA_VERSION,
+        status: "noop",
+        operation: request.operation,
+        inventory: publicInventory(before),
+        detail: publicInventory({ ...before, skills: [skill] }).skills[0],
+      };
+    }
+    const mutation = {
+      action: request.operation,
+      name: skill?.name ?? request.name,
+      ...(request.content !== undefined ? { content: request.content } : {}),
+      ...(request.category !== undefined ? { category: request.category } : {}),
+      ...(request.filePath !== undefined ? { filePath: request.filePath } : {}),
+      ...(request.enabled !== undefined ? { enabled: request.enabled } : {}),
+    };
+    const result = adapter.mutate(mutation);
+    if (result?.success !== true)
+      return { ok: false, code: "skills_native_refused" };
+    if (existsSync(skillRoot)) {
+      const scan = adapter.scan(skillRoot);
+      if (scan?.ok !== true) fail("skills_scan_refused");
+    }
+    const afterNative = adapter.enumerate({
+      readName: request.operation === "delete" ? undefined : mutation.name,
+    });
+    const after = normalizeEnumeration(afterNative, paths, options.limits);
+    if (
+      !after.complete ||
+      (request.operation !== "delete" &&
+        typeof afterNative.nativeView !== "string")
+    )
+      fail("skills_readback_failed");
+    const afterSkill =
+      after.skills.find((entry) => entry.name === mutation.name) ?? null;
+    if (
+      request.operation === "delete" ? afterSkill !== null : afterSkill === null
+    )
+      fail("skills_readback_failed");
+    if (
+      (request.operation === "edit" &&
+        afterSkill.fileSha256 !==
+          sha256(Buffer.from(request.content, "utf8"))) ||
+      (request.operation === "toggle" &&
+        (afterSkill.enabled !== request.enabled ||
+          after.disabledConfigSha256 === before.disabledConfigSha256)) ||
+      (request.operation === "create" &&
+        afterSkill.fileSha256 !==
+          sha256(Buffer.from(request.content, "utf8"))) ||
+      (request.operation === "write_file" &&
+        !afterSkill.manifest.some(
+          (entry) =>
+            entry.relativePath === request.filePath &&
+            entry.fileSha256 === sha256(Buffer.from(request.content, "utf8"))
+        )) ||
+      (request.operation === "remove_file" &&
+        afterSkill.manifest.some(
+          (entry) => entry.relativePath === request.filePath
+        ))
+    ) {
+      fail("skills_readback_failed");
+    }
+    atomicProof(paths, after);
+    options.markDirty(paths.profileRoot);
+    return {
+      ok: true,
+      schemaVersion: SKILLS_BRIDGE_SCHEMA_VERSION,
+      status: "applied",
+      operation: request.operation,
+      effectId: randomUUID(),
+      inventory: publicInventory(after),
+      detail: afterSkill
+        ? publicInventory({ ...after, skills: [afterSkill] }).skills[0]
+        : null,
+    };
+  } catch (error) {
+    rollback();
+    try {
+      adapter.enumerate();
+    } catch {
+      return { ok: false, code: "skills_rollback_unproven" };
+    }
+    return {
+      ok: false,
+      code: "skills_apply_failed_rolled_back",
+      reason:
+        error instanceof FlySkillsBridgeError
+          ? error.code
+          : "skills_bridge_failed",
+    };
+  }
+}
+
+/**
+ * @param {any} request
+ * @param {{
+ *   profileId?: string,
+ *   dataRoot?: string,
+ *   nativeAdapter?: {enumerate: Function, read: Function, scan: Function, mutate: Function} | null,
+ *   markDirty?: (profileRoot: string) => void,
+ *   lockHeld?: boolean,
+ *   limits?: any,
+ * }} [options]
+ */
+export function executeSkillsBridgeOperation(
+  request,
+  {
+    profileId = process.env.SELLABLE_HERMES_PROFILE_ID,
+    dataRoot = SOUL_BRIDGE_DATA_ROOT,
+    nativeAdapter = null,
+    markDirty = markHermesSnapshotDirty,
+    lockHeld = false,
+    limits = {},
+  } = {}
+) {
+  assertRequest(request);
+  const id = validProfileId(profileId);
+  const paths = soulProfilePaths(id, { dataRoot });
+  const adapter = nativeAdapter ?? defaultAdapter(paths);
+  if (
+    !adapter ||
+    !["enumerate", "read", "scan", "mutate"].every(
+      (name) => typeof adapter[name] === "function"
+    )
+  )
+    fail("skills_native_adapter_rejected");
+  if (typeof markDirty !== "function") fail("skills_dirty_marker_rejected");
+  const run = () =>
+    executeLocked(request, paths, adapter, { markDirty, limits });
+  return lockHeld ? run() : withProfileSoulLock(id, run, { dataRoot });
+}
+
+/**
+ * @param {any} request
+ * @param {{
+ *   procRoot?: string,
+ *   dataRoot?: string,
+ *   nativeAdapter?: {enumerate: Function, read: Function, scan: Function, mutate: Function} | null,
+ *   markDirty?: (profileRoot: string) => void,
+ *   callerProfileId?: string,
+ *   limits?: any,
+ * }} [options]
+ */
+export function executeExternalSkillsBridgeOperation(
+  request,
+  {
+    procRoot = "/proc",
+    dataRoot = SOUL_BRIDGE_DATA_ROOT,
+    nativeAdapter = null,
+    markDirty = markHermesSnapshotDirty,
+    callerProfileId = process.env.SELLABLE_HERMES_PROFILE_ID,
+    limits = {},
+  } = {}
+) {
+  const gateway = discoverLiveHermesGateway({ procRoot, dataRoot });
+  if (callerProfileId && callerProfileId !== gateway.profileId)
+    fail("skills_gateway_caller_profile_mismatch");
+  revalidateLiveHermesGateway(gateway, { procRoot, dataRoot });
+  const result = executeSkillsBridgeOperation(request, {
+    profileId: gateway.profileId,
+    dataRoot,
+    nativeAdapter,
+    markDirty,
+    limits,
+  });
+  revalidateLiveHermesGateway(gateway, { procRoot, dataRoot });
+  return Object.freeze({
+    ...result,
+    profileId: gateway.profileId,
+    gatewayPid: gateway.pid,
+    gatewayStartTicks: gateway.startTicks,
+  });
+}
+
+export function computeSkillsConfigIdentity(profileRoot) {
+  if (!isAbsolute(profileRoot) || !existsSync(profileRoot))
+    fail("skills_profile_root_rejected");
+  const canonical = realpathSync(profileRoot);
+  const skillsRoot = join(canonical, "skills");
+  const tree = existsSync(skillsRoot)
+    ? inspectTree(skillsRoot, {
+        maxFiles: 4096,
+        maxTotalBytes: 64 * 1024 * 1024,
+      })
+    : { entries: [], incompleteReason: null };
+  if (tree.incompleteReason) fail("skills_profile_identity_incomplete");
+  const configPath = join(canonical, "config.yaml");
+  const configSha256 = existsSync(configPath)
+    ? sha256(regularFile(configPath, 2 * 1024 * 1024))
+    : sha256("");
+  return Object.freeze({
+    inventorySha256: sha256(stableJson(tree.entries)),
+    disabledConfigSha256: configSha256,
+  });
+}
+
+export function readSkillsProofObservation(profileRoot) {
+  try {
+    const path = join(
+      realpathSync(profileRoot),
+      ".sellable-agent",
+      "skills-proof.json"
+    );
+    const value = JSON.parse(regularFile(path, 4096).toString("utf8"));
+    if (
+      value.schemaVersion !== SKILLS_PROOF_SCHEMA_VERSION ||
+      !SHA256.test(value.inventorySha256 ?? "") ||
+      !SHA256.test(value.disabledConfigSha256 ?? "") ||
+      Object.keys(value).length !== 3
+    )
+      return null;
+    return Object.freeze({
+      inventorySha256: value.inventorySha256,
+      disabledConfigSha256: value.disabledConfigSha256,
+    });
+  } catch {
+    return null;
+  }
+}