@vellumai/assistant 0.8.1 → 0.8.2

package/ARCHITECTURE.md

@@ -1227,9 +1227,8 @@ graph TB
 
     subgraph "2. Persist (Filesystem)"
         SCAFFOLD["scaffold_managed_skill<br/>───────────────<br/>RiskLevel: High<br/>Requires user consent"]
-        MANAGED_STORE["managed-store.ts<br/>───────────────<br/>validateManagedSkillId()<br/>buildSkillMarkdown()<br/>createManagedSkill()<br/>upsertSkillsIndexEntry()"]
+        MANAGED_STORE["managed-store.ts<br/>───────────────<br/>validateManagedSkillId()<br/>buildSkillMarkdown()<br/>createManagedSkill()"]
         SKILL_DIR["~/.vellum/workspace/skills/&lt;id&gt;/<br/>SKILL.md (frontmatter + body)"]
-        INDEX["~/.vellum/workspace/skills/<br/>SKILLS.md (index)"]
     end
 
     subgraph "3. Load & Use"
@@ -1240,7 +1239,6 @@ graph TB
     subgraph "4. Delete"
         DELETE["delete_managed_skill<br/>───────────────<br/>RiskLevel: High<br/>Requires user consent"]
         RM_DIR["rmSync skill directory"]
-        RM_INDEX["removeSkillsIndexEntry()"]
     end
 
     subgraph "File Watcher"
@@ -1257,17 +1255,14 @@ graph TB
 
     SCAFFOLD --> MANAGED_STORE
     MANAGED_STORE --> SKILL_DIR
-    MANAGED_STORE --> INDEX
 
     SKILL_DIR --> WATCHER
-    INDEX --> WATCHER
     WATCHER --> EVICT
 
     SKILL_DIR --> SKILL_LOAD
     SKILL_LOAD --> SESSION
 
     DELETE --> RM_DIR
-    DELETE --> RM_INDEX
     RM_DIR --> WATCHER
 ```
 
@@ -1275,7 +1270,7 @@ graph TB
 
 - `evaluate_typescript_code` always forces `sandbox.enabled = true` regardless of global config.
 - Snippet contract: must export `default` or `run` with signature `(input: unknown) => unknown | Promise<unknown>`.
-- Managed-store writes are atomic (tmp file + rename) to prevent partial `SKILL.md` or `SKILLS.md` files.
+- Managed-store writes are atomic (tmp file + rename) to prevent partial `SKILL.md` files.
 - After persist or delete, the file watcher triggers conversation eviction; the next turn runs in a fresh conversation. The model's system prompt instructs it to continue normally.
 - macOS UI shows Inspect and Delete controls for managed skills only (source = "managed").
 - `skill_load` resolves the recursive include graph (via `include-graph.ts`) before emitting output. Missing children are listed as suggested skills without child `<loaded_skill>` markers; cycles still produce `isError: true` with no marker. Valid includes produce an "Included Skills (immediate)" metadata section showing child ID, name, description, and path.

package/Dockerfile

@@ -73,6 +73,9 @@ RUN apt-get update && apt-get install -y \
     bubblewrap \
     ca-certificates \
     curl \
+    debootstrap \
+    debian-archive-keyring \
+    debconf \
     ffmpeg \
     fonts-freefont-ttf \
     g++ \
@@ -117,6 +120,7 @@ RUN apt-get update && apt-get install -y \
     unzip \
     uuid-runtime \
     vim \
+    wget \
     xclip \
     xdg-utils \
     && rm -rf /var/lib/apt/lists/*
@@ -147,6 +151,76 @@ ENV PATH="${BUN_INSTALL}/bin:${PATH}"
 ENV PYTHONUSERBASE="/home/assistant/.python"
 ENV PATH="${PYTHONUSERBASE}/bin:${PATH}"
 
+RUN printf '%s\n' \
+    'if [ -r /app/assistant/docker-kata-apt-env.sh ]; then' \
+    '  . /app/assistant/docker-kata-apt-env.sh' \
+    'fi' \
+    > /etc/profile.d/vellum-kata-apt-root.sh && \
+    printf '%s\n' \
+    '' \
+    'if [ -r /etc/profile.d/vellum-kata-apt-root.sh ]; then' \
+    '  . /etc/profile.d/vellum-kata-apt-root.sh' \
+    'fi' \
+    >> /etc/bash.bashrc && \
+    printf '%s\n' \
+    '' \
+    'if [ -r /etc/profile.d/vellum-kata-apt-root.sh ]; then' \
+    '  . /etc/profile.d/vellum-kata-apt-root.sh' \
+    'fi' \
+    >> /root/.bashrc && \
+    printf '%s\n' \
+    '' \
+    'if [ -r /etc/profile.d/vellum-kata-apt-root.sh ]; then' \
+    '  . /etc/profile.d/vellum-kata-apt-root.sh' \
+    'fi' \
+    >> /home/assistant/.bashrc && \
+    chown assistant:assistant /home/assistant/.bashrc
+
+RUN printf '%s\n' \
+    '#!/usr/bin/env sh' \
+    'set -eu' \
+    'if [ "${VELLUM_SANDBOX_RUNTIME:-}" != "kata" ]; then' \
+    '  exec /usr/bin/apt-get "$@"' \
+    'fi' \
+    'export DEBIAN_FRONTEND=noninteractive' \
+    'DATA_ROOT="${VELLUM_APT_DATA_ROOT:-/data/system}"' \
+    '/app/assistant/docker-init-apt-root.sh' \
+    'if [ -x "${DATA_ROOT}/bin/sh" ] && [ -x "${DATA_ROOT}/usr/bin/apt-get" ] && [ -f "${DATA_ROOT}/.rootfs-initialized" ] && ! grep -qs " ${DATA_ROOT} .*noexec" /proc/mounts; then' \
+    '  exec chroot "${DATA_ROOT}" /usr/bin/apt-get "$@"' \
+    'fi' \
+    'exec /usr/bin/apt-get "$@"' \
+    > /usr/local/bin/apt-get && \
+    chmod +x /usr/local/bin/apt-get && \
+    printf '%s\n' \
+    '#!/usr/bin/env sh' \
+    'set -eu' \
+    'if [ "${VELLUM_SANDBOX_RUNTIME:-}" != "kata" ]; then' \
+    '  exec /usr/bin/apt "$@"' \
+    'fi' \
+    'export DEBIAN_FRONTEND=noninteractive' \
+    'DATA_ROOT="${VELLUM_APT_DATA_ROOT:-/data/system}"' \
+    '/app/assistant/docker-init-apt-root.sh' \
+    'if [ -x "${DATA_ROOT}/bin/sh" ] && [ -x "${DATA_ROOT}/usr/bin/apt" ] && [ -f "${DATA_ROOT}/.rootfs-initialized" ] && ! grep -qs " ${DATA_ROOT} .*noexec" /proc/mounts; then' \
+    '  exec chroot "${DATA_ROOT}" /usr/bin/apt "$@"' \
+    'fi' \
+    'exec /usr/bin/apt "$@"' \
+    > /usr/local/bin/apt && \
+    chmod +x /usr/local/bin/apt && \
+    printf '%s\n' \
+    '#!/usr/bin/env sh' \
+    'set -eu' \
+    'if [ "${VELLUM_SANDBOX_RUNTIME:-}" != "kata" ]; then' \
+    '  exec /usr/bin/dpkg "$@"' \
+    'fi' \
+    'DATA_ROOT="${VELLUM_APT_DATA_ROOT:-/data/system}"' \
+    '/app/assistant/docker-init-apt-root.sh' \
+    'if [ -x "${DATA_ROOT}/bin/sh" ] && [ -x "${DATA_ROOT}/usr/bin/dpkg" ] && [ -f "${DATA_ROOT}/.rootfs-initialized" ] && ! grep -qs " ${DATA_ROOT} .*noexec" /proc/mounts; then' \
+    '  exec chroot "${DATA_ROOT}" /usr/bin/dpkg "$@"' \
+    'fi' \
+    'exec /usr/bin/dpkg "$@"' \
+    > /usr/local/bin/dpkg && \
+    chmod +x /usr/local/bin/dpkg
+
 # Ensure the CES bootstrap socket volume is writable by the non-root CES user.
 RUN mkdir -p /run/ces-bootstrap && chmod 777 /run/ces-bootstrap
 
@@ -161,7 +235,7 @@ ENV IS_CONTAINERIZED=true
 # and the generated meet-join manifest from the builder stage.
 COPY --from=builder /app /app
 
-RUN chmod +x /app/assistant/docker-entrypoint.sh
+RUN chmod +x /app/assistant/docker-entrypoint.sh /app/assistant/docker-init-apt-root.sh /app/assistant/docker-kata-apt-env.sh
 
 # Run the daemon + http server
 CMD ["/app/assistant/docker-entrypoint.sh"]

package/bun.lock

@@ -37,6 +37,7 @@
         "playwright": "1.58.2",
         "postgres": "3.4.8",
         "rrule": "2.8.1",
+        "semver": "7.8.0",
         "stemmer": "2.0.1",
         "tar-stream": "3.1.7",
         "tldts": "7.0.25",
@@ -48,6 +49,7 @@
         "@types/archiver": "7.0.0",
         "@types/bun": "1.3.10",
         "@types/node": "25.5.0",
+        "@types/semver": "7.5.8",
         "@types/uuid": "10.0.0",
         "drizzle-kit": "0.30.6",
         "eslint": "10.0.3",
@@ -388,6 +390,8 @@
 
     "@types/retry": ["@types/retry@0.12.0", "", {}, "sha512-wWKOClTTiizcZhXnPY4wikVAwmdYHp8q6DmC+EJUzAMsycb7HB32Kh9RN4+0gExjmPmZSAQjgURXIGATPegAvA=="],
 
+    "@types/semver": ["@types/semver@7.5.8", "", {}, "sha512-I8EUhyrgfLrcTkzV3TSsGyl1tSuPrEDzr0yd5m90UgNxQkyDXULk3b6MlQqTCpZpNtWe1K0hzclnZkTcLBe2UQ=="],
+
     "@types/tedious": ["@types/tedious@4.0.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-KHPsfX/FoVbUGbyYvk1q9MMQHLPeRZhRJZdO45Q4YjvFkv4hMNghCWTvy7rdKessBsmtz4euWCWAB6/tVpI1Iw=="],
 
     "@types/uuid": ["@types/uuid@10.0.0", "", {}, "sha512-7gqG38EyHgyP1S+7+xomFtL+ZNHcKv6DwNaCZmJmo1vgMugyF3TCnXVg4t1uk89mLNwnLtnY3TpOpCOyp1/xHQ=="],
@@ -1080,7 +1084,7 @@
 
     "secure-json-parse": ["secure-json-parse@4.1.0", "", {}, "sha512-l4KnYfEyqYJxDwlNVyRfO2E4NTHfMKAWdUuA8J0yve2Dz/E/PdBepY03RvyJpssIpRFwJoCD55wA+mEDs6ByWA=="],
 
-    "semver": ["semver@7.7.4", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA=="],
+    "semver": ["semver@7.8.0", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA=="],
 
     "send": ["send@1.2.1", "", { "dependencies": { "debug": "^4.4.3", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "etag": "^1.8.1", "fresh": "^2.0.0", "http-errors": "^2.0.1", "mime-types": "^3.0.2", "ms": "^2.1.3", "on-finished": "^2.4.1", "range-parser": "^1.2.1", "statuses": "^2.0.2" } }, "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ=="],
 
@@ -1248,6 +1252,8 @@
 
     "@typescript-eslint/eslint-plugin/ignore": ["ignore@7.0.5", "", {}, "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg=="],
 
+    "@typescript-eslint/typescript-estree/semver": ["semver@7.7.4", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA=="],
+
     "@vellumai/ces-client/@types/bun": ["@types/bun@1.2.4", "", { "dependencies": { "bun-types": "1.2.4" } }, "sha512-QtuV5OMR8/rdKJs213iwXDpfVvnskPXY/S0ZiFbsTjQZycuqPbMW8Gf/XhLfwE5njW8sxI2WjISURXPlHypMFA=="],
 
     "@vellumai/ces-client/@vellumai/service-contracts": ["@vellumai/service-contracts@file:../packages/service-contracts", { "dependencies": { "zod": "4.3.6" }, "devDependencies": { "@types/bun": "1.2.4", "typescript": "5.7.3" } }],
@@ -1274,6 +1280,8 @@
 
     "foreground-child/signal-exit": ["signal-exit@4.1.0", "", {}, "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw=="],
 
+    "gel/semver": ["semver@7.7.4", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA=="],
+
     "glob/minimatch": ["minimatch@9.0.9", "", { "dependencies": { "brace-expansion": "^2.0.2" } }, "sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg=="],
 
     "jszip/readable-stream": ["readable-stream@2.3.8", "", { "dependencies": { "core-util-is": "~1.0.0", "inherits": "~2.0.3", "isarray": "~1.0.0", "process-nextick-args": "~2.0.0", "safe-buffer": "~5.1.1", "string_decoder": "~1.1.1", "util-deprecate": "~1.0.1" } }, "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA=="],
@@ -1380,6 +1388,8 @@
 
     "detective-typescript/@typescript-eslint/typescript-estree/@typescript-eslint/visitor-keys": ["@typescript-eslint/visitor-keys@8.59.1", "", { "dependencies": { "@typescript-eslint/types": "8.59.1", "eslint-visitor-keys": "^5.0.0" } }, "sha512-LdDNl6C5iJExcM0Yh0PwAIBb9PrSiCsWamF/JyEZawm3kFDnRoaq3LGE4bpyRao/fWeGKKyw7icx0YxrLFC5Cg=="],
 
+    "detective-typescript/@typescript-eslint/typescript-estree/semver": ["semver@7.7.4", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA=="],
+
     "glob/minimatch/brace-expansion": ["brace-expansion@2.1.0", "", { "dependencies": { "balanced-match": "^1.0.0" } }, "sha512-TN1kCZAgdgweJhWWpgKYrQaMNHcDULHkWwQIspdtjV4Y5aurRdZpjAqn6yX3FPqTA9ngHCc4hJxMAMgGfve85w=="],
 
     "jszip/readable-stream/string_decoder": ["string_decoder@1.1.1", "", { "dependencies": { "safe-buffer": "~5.1.0" } }, "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg=="],

package/docker-entrypoint.sh

@@ -5,6 +5,11 @@ set -eu
 # processes (the `assistant` user, bun's tmpdir, scratch writes) can use it.
 chmod 1777 /tmp 2>/dev/null || true
 
+if [ "${VELLUM_SANDBOX_RUNTIME:-}" = "kata" ] && [ -x /app/assistant/docker-init-apt-root.sh ]; then
+  . /app/assistant/docker-kata-apt-env.sh
+  /app/assistant/docker-init-apt-root.sh
+fi
+
 if [ "$(id -u)" = "0" ] && [ "${VELLUM_WORKSPACE_DIR:-}" = "/workspace" ] && [ -d /workspace ]; then
   git config --global --add safe.directory /workspace >/dev/null 2>&1 || true
   git config --global --add safe.directory '/workspace/*' >/dev/null 2>&1 || true

package/docker-init-apt-root.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env sh
+set -eu
+
+DATA_ROOT="${VELLUM_APT_DATA_ROOT:-/data/system}"
+SENTINEL="${DATA_ROOT}/.rootfs-initialized"
+HOST_PATH="/usr/sbin:/usr/bin:/sbin:/bin"
+
+if [ "${VELLUM_SANDBOX_RUNTIME:-}" != "kata" ]; then
+  exit 0
+fi
+
+# Bootstrap the alternate root with the host toolchain so the wrapper
+# binaries in /usr/local/bin do not recurse back into this script.
+export PATH="${HOST_PATH}"
+
+check_sane_mount() {
+  target="$1"
+  probe_dev="${target}/.apt-test-dev-null"
+  probe_exec="${target}/.apt-test-exec"
+  shell_path="/bin/sh"
+
+  mkdir -p "${target}"
+
+  if ! mknod "${probe_dev}" c 1 3 2>/dev/null || ! echo test >"${probe_dev}"; then
+    rm -f "${probe_dev}"
+    : >"${probe_dev}"
+    if ! mount -o bind /dev/null "${probe_dev}" >/dev/null 2>&1; then
+      rm -f "${probe_dev}"
+      return 1
+    fi
+    if ! echo test >"${probe_dev}"; then
+      umount "${probe_dev}" >/dev/null 2>&1 || true
+      rm -f "${probe_dev}"
+      return 1
+    fi
+    umount "${probe_dev}" >/dev/null 2>&1 || true
+  fi
+  rm -f "${probe_dev}"
+
+  if [ ! -x "${shell_path}" ]; then
+    shell_path="$(command -v sh)"
+  fi
+
+  cat >"${probe_exec}" <<EOF
+#! ${shell_path}
+:
+EOF
+  chmod +x "${probe_exec}"
+  if ! "${probe_exec}" >/dev/null 2>&1; then
+    rm -f "${probe_exec}"
+    return 1
+  fi
+  rm -f "${probe_exec}"
+
+  return 0
+}
+
+if [ -f "${SENTINEL}" ] && [ -x "${DATA_ROOT}/bin/sh" ] && [ -x "${DATA_ROOT}/usr/bin/apt-get" ]; then
+  exit 0
+fi
+
+if grep -qs " ${DATA_ROOT} .*noexec" /proc/mounts; then
+  echo "Warning: ${DATA_ROOT} is mounted noexec; skipping persistent apt rootfs bootstrap" >&2
+  exit 0
+fi
+
+if ! check_sane_mount "${DATA_ROOT}"; then
+  echo "Warning: ${DATA_ROOT} cannot host a chrootable apt rootfs here; falling back to image-root apt installs" >&2
+  exit 0
+fi
+
+if [ -x "${DATA_ROOT}/bin/sh" ] && [ -x "${DATA_ROOT}/usr/bin/apt-get" ]; then
+  touch "${SENTINEL}"
+  exit 0
+fi
+
+SUITE="${VELLUM_APT_DATA_SUITE:-}"
+if [ -z "${SUITE}" ] && [ -r /etc/os-release ]; then
+  # shellcheck disable=SC1091
+  . /etc/os-release
+  SUITE="${VERSION_CODENAME:-trixie}"
+fi
+if [ -z "${SUITE}" ]; then
+  SUITE="trixie"
+fi
+
+MIRROR="${VELLUM_APT_DATA_MIRROR:-http://deb.debian.org/debian}"
+ARCH="$(/usr/bin/dpkg --print-architecture)"
+
+mkdir -p "${DATA_ROOT}"
+
+debootstrap --variant=minbase --arch="${ARCH}" "${SUITE}" "${DATA_ROOT}" "${MIRROR}"
+
+touch "${SENTINEL}"

package/docker-kata-apt-env.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env sh
+
+if [ "${VELLUM_SANDBOX_RUNTIME:-}" != "kata" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+export VELLUM_APT_DATA_ROOT="${VELLUM_APT_DATA_ROOT:-/data/system}"
+
+_vellum_kata_append_path() {
+  case ":${PATH:-}:" in
+    *":$1:"*) ;;
+    *) PATH="${PATH:+${PATH}:}$1" ;;
+  esac
+}
+
+_vellum_kata_prepend_library_path() {
+  case ":${LD_LIBRARY_PATH:-}:" in
+    *":$1:"*) ;;
+    *) LD_LIBRARY_PATH="$1${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}" ;;
+  esac
+}
+
+_vellum_kata_append_path "${VELLUM_APT_DATA_ROOT}/bin"
+_vellum_kata_append_path "${VELLUM_APT_DATA_ROOT}/usr/local/sbin"
+_vellum_kata_append_path "${VELLUM_APT_DATA_ROOT}/usr/local/bin"
+_vellum_kata_append_path "${VELLUM_APT_DATA_ROOT}/usr/sbin"
+_vellum_kata_append_path "${VELLUM_APT_DATA_ROOT}/usr/bin"
+_vellum_kata_append_path "${VELLUM_APT_DATA_ROOT}/sbin"
+_vellum_kata_append_path "${VELLUM_APT_DATA_ROOT}/usr/games"
+_vellum_kata_append_path "${VELLUM_APT_DATA_ROOT}/games"
+export PATH
+
+_vellum_kata_prepend_library_path "${VELLUM_APT_DATA_ROOT}/usr/lib/aarch64-linux-gnu"
+_vellum_kata_prepend_library_path "${VELLUM_APT_DATA_ROOT}/usr/lib/x86_64-linux-gnu"
+_vellum_kata_prepend_library_path "${VELLUM_APT_DATA_ROOT}/usr/lib"
+_vellum_kata_prepend_library_path "${VELLUM_APT_DATA_ROOT}/usr/local/lib"
+export LD_LIBRARY_PATH
+
+unset -f _vellum_kata_append_path _vellum_kata_prepend_library_path

package/docs/plugins.md

@@ -94,8 +94,6 @@ time. Its shape (see
 export interface PluginManifest {
   name: string; // kebab-case, unique
   version: string; // semver, informational
-  provides?: Record<string, string>; // reserved; not consumed at runtime today
-  requires: Record<string, string>; // capability → version required from the assistant
   requiresCredential?: string[]; // credential keys resolved before init()
   requiresFlag?: string[]; // feature flag keys that must all be enabled
   config?: unknown; // Zod-like parser for plugins.<name>
@@ -104,25 +102,45 @@ export interface PluginManifest {
 
 | Field                | Required | Purpose                                                                                                                                                                                                                                                                                                        |
 | -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`               | yes      | Unique plugin identifier. Duplicate names fail registration. Used as the directory under `<workspaceDir>/plugins-data/<name>/` and the attribution tag in logs.                                                                                                                                                     |
+| `name`               | yes      | Unique plugin identifier. Duplicate names fail registration. Used as the directory under `<workspaceDir>/plugins-data/<name>/` and the attribution tag in logs.                                                                                                                                                |
 | `version`            | yes      | Plugin's own semver. Informational — the registry does not compare it.                                                                                                                                                                                                                                         |
-| `provides`           | no       | Reserved for future cross-plugin composition and not currently consumed by the assistant. Plugin authors may set this field, but no runtime code reads it yet — it is declared here so future cross-plugin work can land without a manifest version bump. Do not rely on it for any runtime behavior today.    |
-| `requires`           | yes      | Must include `pluginRuntime: "v1"` at minimum. The registry checks every entry against `ASSISTANT_API_VERSIONS` and refuses to register plugins that ask for a capability or version the assistant does not expose.                                                                                            |
 | `requiresCredential` | no       | Credential keys the plugin needs. The bootstrap resolves them via the credential store before `init()` runs and hands the values to the plugin in `ctx.credentials`. A missing credential fails startup with a clear error.                                                                                    |
 | `requiresFlag`       | no       | Assistant feature-flag keys that must all be ON for the plugin to activate. If any listed flag is disabled at bootstrap, the plugin is skipped entirely: `init()` is not invoked and no tools, routes, skills, or shutdown hooks are registered for it. See [Feature-flag gating](#feature-flag-gating) below. |
 | `config`             | no       | A parser-like validator (Zod schema, or any object with a `.parse(input)` method). If supplied, the bootstrap validates `config.plugins.<name>` through it before passing the result into `init()`.                                                                                                            |
 
-The exposed capability table (`ASSISTANT_API_VERSIONS`) lives in
-[`registry.ts`](../src/plugins/registry.ts). It lists:
+### Host-compat: `peerDependencies["@vellumai/plugin-api"]`
 
-- `pluginRuntime` — the base runtime every plugin must negotiate for.
-- `memoryApi`, `compactionApi`, `persistenceApi` — top-level subsystem APIs.
-- One `*Api` entry per pipeline slot (e.g. `llmCallApi`, `toolExecuteApi`,
-  `titleGenerateApi`, …).
+Plugins declare which assistant versions they support via standard
+`peerDependencies` in their `package.json`:
 
-Every entry is currently on `v1`. Removing or changing a version tag is a
-breaking change — plugins relying on it will fail to register until they
-update their `requires` map.
+```json
+{
+  "name": "@me/my-logger",
+  "version": "1.2.3",
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  }
+}
+```
+
+At load time, the external-plugin loader resolves the assistant's running
+version and runs `semver.satisfies(assistantVersion, range)` against the
+declared range. The contract is currently soft while the plugin-installation
+flow is in flux:
+
+- **Range satisfied** — plugin loads.
+- **Range not satisfied** — loader logs an error (`log.error`) and loads
+  the plugin anyway.
+- **Range unparseable** — loader logs an error and loads the plugin anyway.
+- **`@vellumai/plugin-api` peerDep absent** — loader logs a warning and
+  loads the plugin without a host-compat claim.
+
+Once the install flow settles, the two error-logging branches above will
+harden into hard rejections (with per-plugin isolation catching the
+throw so one bad plugin can't brick the rest of the registry).
+
+In-tree default plugins do not declare a peerDep — they ship with the
+assistant binary and are version-locked by construction.
 
 ### Example manifest
 
@@ -130,11 +148,6 @@ update their `requires` map.
 const manifest: PluginManifest = {
   name: "my-logger",
   version: "1.2.3",
-  provides: {},
-  requires: {
-    pluginRuntime: "v1",
-    llmCallApi: "v1",
-  },
   requiresCredential: ["LOGGER_API_KEY"],
   requiresFlag: ["my-logger-enabled"],
   config: z.object({
@@ -179,17 +192,33 @@ Feature Flags" section for the full procedure.
 
 ## Registration
 
-A plugin's `register.ts` calls `registerPlugin()` at module load time:
+A plugin's `register.ts` calls `registerPlugin()` at module load time. The
+function is exposed via the `globalThis.__vellumPluginRuntime` bridge so the
+plugin file does not need to import from the daemon's source tree:
 
 ```typescript
-import { registerPlugin } from "<path-to-assistant>/src/plugins/registry.js";
 import type { Plugin } from "<path-to-assistant>/src/plugins/types.js";
 
+interface VellumPluginRuntime {
+  readonly version: 1;
+  readonly registerPlugin: (plugin: Plugin) => void;
+  readonly assistantEventHub: import("<path-to-assistant>/src/runtime/assistant-event-hub.js").AssistantEventHub;
+  readonly getSecureKeyAsync: (account: string) => Promise<string | undefined>;
+}
+
+const runtime = (globalThis as { __vellumPluginRuntime?: VellumPluginRuntime })
+  .__vellumPluginRuntime;
+if (!runtime || runtime.version !== 1) {
+  throw new Error(
+    "vellum plugin runtime not available — install a recent assistant build",
+  );
+}
+const { registerPlugin } = runtime;
+
 const myPlugin: Plugin = {
   manifest: {
     name: "my-plugin",
     version: "0.1.0",
-    requires: { pluginRuntime: "v1" },
   },
   middleware: {
     /* ... */
@@ -199,6 +228,20 @@ const myPlugin: Plugin = {
 registerPlugin(myPlugin);
 ```
 
+**Why the bridge?** When the daemon is a `bun --compile` binary, its modules
+are bundled into the executable. Plugins that import the daemon's modules by
+absolute path (`/abs/path/to/assistant/src/plugins/registry.js`) reload fresh
+disk copies into a separate module graph, and any `registerPlugin()` call in
+the plugin lands in a registry the daemon never reads. The
+`globalThis.__vellumPluginRuntime` handle is the same instance the daemon's
+bundled code holds onto, so plugin registrations always reach the right
+place — whether the daemon was built with `bun --compile` or is running from
+source.
+
+Type-only imports (`import type { Plugin } from "..."`) remain free to use
+absolute paths to the assistant source — the TypeScript compiler erases them
+and they have no module-identity effect at runtime.
+
 **Rules:**
 
 - Exactly one `registerPlugin()` call per plugin. The registry rejects
@@ -210,6 +253,8 @@ registerPlugin(myPlugin);
   this plugin" — use `requiresFlag` or a guard inside `init()` instead.
 - The file runs before any lifecycle hooks. Keep it fast — heavy work
   belongs in `init()`.
+- The bridge is installed by the daemon before `loadUserPlugins()` runs, so
+  the global is always present when a plugin's module body executes.
 
 ## Middleware patterns
 
@@ -419,7 +464,6 @@ Declare required credential keys in `manifest.requiresCredential`:
 const manifest: PluginManifest = {
   name: "my-plugin",
   version: "1.0.0",
-  requires: { pluginRuntime: "v1" },
   requiresCredential: ["MY_PLUGIN_API_KEY"],
 };
 ```
@@ -458,7 +502,6 @@ const configSchema = z.object({
 const manifest: PluginManifest = {
   name: "my-plugin",
   version: "1.0.0",
-  requires: { pluginRuntime: "v1" },
   config: configSchema,
 };
 ```
@@ -487,8 +530,8 @@ export interface PluginInitContext {
   credentials: Record<string, string>; // resolved credentials from requiresCredential
   logger: unknown; // pino child logger, tagged { plugin: <name> }
   pluginStorageDir: string; // <workspaceDir>/plugins-data/<name>/ (created by bootstrap)
-  assistantVersion: string; // assistant semver
-  apiVersions: Record<string, string[]>; // ASSISTANT_API_VERSIONS, for runtime checks
+  assistantVersion: string; // assistant semver — same value used by the loader
+  //                          against your peerDependencies range
 }
 ```
 
@@ -635,14 +678,6 @@ assistant's module graph.
 Do not add new HTTP endpoints to implement plugin-to-plugin messaging
 inside a single assistant process.
 
-`manifest.provides` is reserved as the hook for a future cross-plugin
-capability-negotiation protocol but is **not currently consumed by any
-runtime code**. Declaring `provides` today has no behavioral effect —
-plugins must not depend on it for capability discovery or any other
-runtime purpose. The field is intentionally retained on the manifest so
-that adding real consumers later does not require bumping
-`pluginRuntime` or any other capability version.
-
 ## Hot reload
 
 **Not supported in v1.** Registering a plugin takes effect at assistant
@@ -661,23 +696,29 @@ loop externally.
 
 ## Troubleshooting
 
-### "plugin X must declare requires.pluginRuntime"
+### `external plugin X: peerDependencies["@vellumai/plugin-api"] requires "<range>" but assistant is <version> — loading anyway`
 
-The manifest's `requires` map is missing the `pluginRuntime` entry. Every
-plugin must negotiate against the base runtime:
+Logged at `error` level. Your plugin's declared
+`peerDependencies["@vellumai/plugin-api"]` range does not include the
+running assistant's version. The plugin still loads while the install
+flow is being shaped, but a future release will turn this into a hard
+rejection. Either widen the range in your `package.json` (typically by
+bumping the major in `^X.Y.Z`) or upgrade the assistant.
 
-```typescript
-requires: { pluginRuntime: "v1" },
-```
+### `external plugin X: peerDependencies["@vellumai/plugin-api"] is not a valid semver range — loading anyway`
+
+Logged at `error` level, same lenient policy as above. The value declared
+under `peerDependencies["@vellumai/plugin-api"]` is not parseable as a
+semver range. Use a standard range expression such as `^0.8.0`,
+`>=0.8.0 <0.10`, or an exact version.
 
-### "plugin X requires Y@vN, assistant exposes (none|v...)"
+### `external plugin X missing plugin-api peerDependency — loading without host-compat claim`
 
-The `requires` map names a capability the assistant does not expose, or
-asks for a version not listed under that capability. See
-`ASSISTANT_API_VERSIONS` in
-[`registry.ts`](../src/plugins/registry.ts) for the currently-exposed
-list. Either downgrade the required version or update your plugin to
-match.
+Warning, not an error. Your plugin's `package.json` does not declare a
+`peerDependencies["@vellumai/plugin-api"]` entry, so the loader has no
+host-compat range to check and loads the plugin without that guard. Add
+the peerDep so future assistant upgrades surface incompatibility before
+the plugin runs.
 
 ### "plugin X is already registered"
 

package/docs/skills.md

@@ -6,20 +6,22 @@ This document describes the security model for the Vellum Assistant skill system
 
 Skills extend the assistant's capabilities by providing instructions (via `SKILL.md`) and optional custom tools (via `TOOLS.json`). Skills can be **bundled** (shipped with the application), **managed** (user-installed via `scaffold_managed_skill`), **workspace** (project-local), or **extra** (additional directories configured by the user).
 
+For managed skills, the installed source of truth is a valid directory at `~/.vellum/workspace/skills/<id>/` containing a top-level `SKILL.md` with standardized frontmatter. The assistant parses that frontmatter at startup and when skill directories change, then seeds Memory V2 skill entries under `skills/<id>` so the assistant can discover available skills from memory. The legacy `SKILLS.md` index is removed by workspace migration and is no longer created by install or scaffold paths.
+
 Because skills can introduce arbitrary tool behavior, they are subject to stricter permission defaults than core tools.
 
 ## Permission Defaults for Skill Tools
 
 Skill-origin tools follow a stricter default permission policy than core tools:
 
-| Scenario                                          | Core tool behavior            | Skill tool behavior |
-| ------------------------------------------------- | ----------------------------- | ------------------- |
+| Scenario                                          | Core tool behavior                  | Skill tool behavior |
+| ------------------------------------------------- | ----------------------------------- | ------------------- |
 | Low risk, no matching rule                        | Auto-allowed (at default threshold) | **Prompted**        |
-| Medium risk, no matching rule                     | Prompted                      | Prompted            |
-| High risk, no matching rule                       | Prompted                      | Prompted            |
-| Allow rule matches, non-high risk                 | Auto-allowed                  | Auto-allowed        |
-| Allow rule matches, high risk, containerized bash | Auto-allowed (runtime check)  | Auto-allowed        |
-| Allow rule matches, high risk, other              | Prompted                      | Prompted            |
+| Medium risk, no matching rule                     | Prompted                            | Prompted            |
+| High risk, no matching rule                       | Prompted                            | Prompted            |
+| Allow rule matches, non-high risk                 | Auto-allowed                        | Auto-allowed        |
+| Allow rule matches, high risk, containerized bash | Auto-allowed (runtime check)        | Auto-allowed        |
+| Allow rule matches, high risk, other              | Prompted                            | Prompted            |
 
 Even if a skill's `TOOLS.json` declares `"risk": "low"` for one of its tools, the permission checker will prompt the user unless an explicit trust rule in `~/.vellum/protected/trust.json` allows it. This prevents third-party skill tools from silently auto-executing.