@vellumai/assistant 0.8.1 → 0.8.3

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.
 

package/examples/plugins/echo/README.md

@@ -30,49 +30,49 @@ For the full plugin authoring guide, see
 
 ## Install locally
 
-The assistant scans `~/.vellum/plugins/*` for subdirectories containing a
+The assistant scans `<workspaceDir>/plugins/*` (e.g.
+`~/.vellum/workspace/plugins/`) for subdirectories containing a
 `register.{ts,js}` file and dynamic-imports each one during assistant
 startup. Dropping (or symlinking) this directory in place is enough to
 enable it.
 
-### Option 1 — symlink from the repo (recommended)
+The plugin reads `registerPlugin` from `globalThis.__vellumPluginRuntime`,
+which the daemon attaches before scanning plugins. This works against both
+the `bun --compile`-bundled daemon binary AND a daemon running from
+source — no special install procedure required either way.
+
+### Option 1 — symlink from the repo (simplest in-repo dev)
 
 From the repo root:
 
 ```bash
-mkdir -p ~/.vellum/plugins
-ln -s "$(pwd)/assistant/examples/plugins/echo" ~/.vellum/plugins/echo
+mkdir -p ~/.vellum/workspace/plugins
+ln -s "$(pwd)/assistant/examples/plugins/echo" ~/.vellum/workspace/plugins/echo
 ```
 
 Symlinks let you edit the plugin in-place and restart the assistant to
-pick up changes. **This is the only zero-edit install path** — the
-`register.ts` in this directory uses relative imports
-(`../../../src/plugins/registry.js`) that resolve into the in-repo
-assistant sources, so the file must stay reachable at that relative
-location.
-
-### Option 2 — standalone copy (requires edits)
-
-If you want a fully isolated install that does not depend on a local
-vellum-assistant checkout, a plain `cp -R` of this directory into
-`~/.vellum/plugins/echo/` will **not** work as-is: the relative imports
-in `register.ts` resolve to `~/.vellum/src/plugins/...`, which does not
-exist. The assistant does not currently publish the plugin API as an npm
-package, so to copy-and-adapt this template into a standalone plugin you
-must rewrite the imports in `register.ts` to point at an absolute path
-inside a vellum-assistant checkout, for example:
+pick up changes.
+
+### Option 2 — standalone copy
+
+A plain `cp -R` of this directory into `~/.vellum/workspace/plugins/echo/`
+works for the runtime imports (which go through the global bridge), but
+the `import type` lines at the top of `register.ts` still resolve into
+the in-repo assistant source tree. If your standalone copy lives outside
+a vellum-assistant checkout, rewrite those `import type` paths to point
+at an absolute path inside any checkout — they're erased at compile time
+and have no module-identity effect at runtime:
 
 ```ts
 // before (repo-local):
-import { registerPlugin } from "../../../src/plugins/registry.js";
+import type { VellumPluginRuntime } from "../../../src/plugins/external-api.js";
+import type { Plugin } from "../../../src/plugins/types.js";
 // after (standalone, edit to your checkout path):
-import { registerPlugin } from "/path/to/vellum-assistant/assistant/src/plugins/registry.js";
+import type { VellumPluginRuntime } from "/path/to/vellum-assistant/assistant/src/plugins/external-api.js";
+import type { Plugin } from "/path/to/vellum-assistant/assistant/src/plugins/types.js";
 ```
 
-Apply the same rewrite to the `import type` line that pulls from
-`../../../src/plugins/types.js`. Until a published package exists, the
-symlink recipe above is simpler and more portable for day-to-day
-development.
+No runtime-import rewriting is needed — the bridge already handles that.
 
 ### Restart the assistant
 
@@ -113,7 +113,7 @@ original error still propagates.
 Remove the symlink (or the copied directory) and restart the assistant:
 
 ```bash
-rm ~/.vellum/plugins/echo
+rm ~/.vellum/workspace/plugins/echo
 vellum restart
 ```
 

package/examples/plugins/echo/package.json

@@ -9,6 +9,9 @@
   "engines": {
     "node": ">=20.12.0"
   },
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  },
   "devDependencies": {
     "@types/bun": "1.3.10",
     "@types/node": "25.5.0",

package/examples/plugins/echo/register.ts

@@ -2,34 +2,26 @@
  * Echo plugin — observes every assistant pipeline and logs one structured
  * line per invocation to stderr.
  *
- * This plugin is bundled in the repository as an authoring reference. It is
- * not shipped with the assistant runtime; to try it locally, symlink this
- * directory into `~/.vellum/plugins/echo/` and restart the assistant. See
- * `README.md` in this directory for the full install recipe and
- * `assistant/docs/plugins.md` for general plugin authoring docs.
+ * Bundled in the repository as an authoring reference. To try it locally,
+ * symlink (or copy) this directory into `<workspaceDir>/plugins/echo/` and
+ * restart the assistant. See `README.md` in this directory for the install
+ * recipe and `assistant/docs/plugins.md` for general plugin authoring docs.
  *
- * ## IMPORTANT — imports below are REPO-LOCAL
+ * ## Runtime bridge
  *
- * The relative imports from `../../../src/plugins/...` resolve correctly
- * only while this file lives inside the vellum-assistant repo at
- * `assistant/examples/plugins/echo/`. The path walks back to
- * `assistant/src/plugins/` so the example compiles against the assistant's
- * in-repo types.
+ * The plugin reads `registerPlugin` from `globalThis.__vellumPluginRuntime`,
+ * a stable handle the daemon attaches at startup. This lets the same plugin
+ * file work whether the daemon is running from source (relative or absolute
+ * imports would resolve to the daemon's modules) or as a `bun --compile`
+ * binary (where absolute imports would load a disjoint disk copy with a
+ * separate registry instance). The bridge is documented in
+ * `assistant/src/plugins/external-api.ts`.
  *
- * If you copy (rather than symlink) this directory to
- * `~/.vellum/plugins/echo/`, these imports will fail because
- * `~/.vellum/src/plugins/...` does not exist. The assistant does not
- * currently publish the plugin API as an npm package, so the only
- * zero-edit install path is the symlink recipe (Option 1 in README.md).
- *
- * For a standalone copy that lives outside the repo, you must either:
- * - Point the imports at an absolute path into a vellum-assistant checkout
- *   (`/path/to/vellum-assistant/assistant/src/plugins/registry.js`), or
- * - Rewrite the plugin to consume only the public types you need and drop
- *   the direct registry import in favor of your own entry-point wiring.
- *
- * See README.md "Option 2 — standalone copy" for the recommended
- * standalone-template adaptation steps.
+ * Type imports below still come from the in-repo source tree. Types are
+ * erased at runtime, so they don't affect module identity — but they only
+ * resolve while this file lives inside the vellum-assistant checkout. For a
+ * standalone-copy install, rewrite the `import type` paths to absolute paths
+ * inside a checkout (or vendor only the types you need).
  *
  * ## Design
  *
@@ -48,7 +40,7 @@
  * user-plugin-loader contract (see `assistant/src/plugins/user-loader.ts`).
  */
 
-import { registerPlugin } from "../../../src/plugins/registry.js";
+import type { VellumPluginRuntime } from "../../../src/plugins/external-api.js";
 import type {
   CircuitBreakerArgs,
   CircuitBreakerResult,
@@ -81,6 +73,15 @@ import type {
   TurnResult,
 } from "../../../src/plugins/types.js";
 
+const runtime = (globalThis as { __vellumPluginRuntime?: VellumPluginRuntime })
+  .__vellumPluginRuntime;
+if (!runtime || runtime.version !== 1) {
+  throw new Error(
+    "echo plugin: globalThis.__vellumPluginRuntime is missing or has an unexpected version — install a recent assistant build",
+  );
+}
+const { registerPlugin } = runtime;
+
 const PLUGIN_NAME = "echo";
 
 /**
@@ -136,9 +137,10 @@ function makeObserver<A, R>(
  * `PipelineMiddlewareMap` — all thin observers produced by `makeObserver`.
  *
  * Manifest:
- * - `requires.pluginRuntime: "v1"` satisfies the registry's mandatory
- *   capability negotiation.
- * - `provides: {}` — the plugin exposes no capabilities to other plugins.
+ * - Host-compat range lives in `package.json` under
+ *   `peerDependencies["@vellumai/plugin-api"]`. The external-plugin loader
+ *   validates it against the running assistant version via
+ *   `semver.satisfies()` before this file is even imported.
  * - No `requiresCredential` or `requiresFlag` — the plugin needs no external
  *   state and runs unconditionally.
  */
@@ -146,8 +148,6 @@ const echoPlugin: Plugin = {
   manifest: {
     name: PLUGIN_NAME,
     version: "0.1.0",
-    provides: {},
-    requires: { pluginRuntime: "v1" },
   },
   middleware: {
     turn: makeObserver<TurnArgs, TurnResult>("turn"),