@vellumai/assistant 0.8.0 → 0.8.2

package/eslint-rules/cli-no-daemon-internals.js

@@ -0,0 +1,283 @@
+// Import prefixes allowed for each transport class. Entries cover both
+// depth-1 (e.g. `commands/foo.ts`) and depth-2 (e.g. `commands/oauth/bar.ts`)
+// relative paths so nested command directories don't false-positive.
+//
+// Adding a new entry: prefer the narrowest match that captures the legitimate
+// case. Daemon-internal modules (`runtime/`, `services/`, `agents/`, `llm/`,
+// `skills/`, etc.) MUST remain off the allowlist for `ipc`-tagged commands.
+const ALLOWED_PREFIXES = {
+  ipc: [
+    "node:",
+    "bun:",
+    "commander",
+    // Sibling subcommand composition (e.g. oauth/index.ts -> ./connect.js).
+    // The imported file is itself a command and the rule will check its
+    // imports independently, so this can't be used to smuggle daemon
+    // internals through a sibling re-export.
+    "./",
+    // IPC client at depth-1 and depth-2.
+    "../../ipc/cli-client",
+    "../../../ipc/cli-client",
+    // Status command's daemon-down fallback needs socket path + platform.
+    "../../ipc/socket-path",
+    "../../util/platform",
+    // Logger / output at depth-1 and depth-2.
+    "../logger",
+    "../output",
+    "../../logger",
+    "../../output",
+    // Shared CLI lib / utils at depth-1 and depth-2.
+    "../lib/",
+    "../../lib/",
+    "../utils/",
+    "../../utils/",
+    // Environment access for commands that need to read VELLUM_* env vars
+    // before issuing IPC calls (e.g. email, domain).
+    "../../config/env",
+    // Browser command's operation metadata (drives subcommand generation).
+    "../../browser/operations",
+  ],
+  local: [
+    "node:",
+    "bun:",
+    "commander",
+    "zod",
+    // Sibling helpers + cross-namespace helper for config.ts managed-mode
+    // check (see commands/oauth/shared.ts docstring).
+    "./",
+    // Config schema/loader at depth-1 and depth-2.
+    "../../config/loader",
+    "../../config/schema",
+    "../../config/env",
+    "../../util/platform",
+    "../logger",
+    "../output",
+    "../../logger",
+    "../../output",
+    "../lib/",
+    "../../lib/",
+    "../utils/",
+    "../../utils/",
+    // Secure key storage (keys.ts) needs direct security module access —
+    // by design, the secure-key helpers run in-process (not over IPC).
+    "../../security/",
+    // CES bridge (credential-execution.ts) speaks to the CES sidecar via
+    // service-contracts RPC; daemon is not involved.
+    "../../credential-execution/",
+    "@vellumai/service-contracts",
+  ],
+  bootstrap: [
+    "node:",
+    "bun:",
+    "commander",
+    "./",
+    "../../config/loader",
+    "../../config/schema",
+    "../../config/env",
+    "../../util/platform",
+    "../logger",
+    "../output",
+    "../../logger",
+    "../../output",
+    "../lib/",
+    "../../lib/",
+    "../utils/",
+    "../../utils/",
+  ],
+};
+
+/**
+ * Walks the program AST looking for a `registerCommand({ transport: ... })`
+ * call. Returns:
+ *   - the transport string when registerCommand is called with a string
+ *     transport prop ("ipc" / "local" / "bootstrap")
+ *   - "MISSING_TRANSPORT" when registerCommand is called but no string
+ *     transport prop is present
+ *   - null when no registerCommand call is found at all (helper module —
+ *     not a command entry, no checks apply)
+ */
+function findTransport(program) {
+  const worklist = [...program.body];
+  const seen = new WeakSet();
+  let registerCommandCalled = false;
+
+  while (worklist.length > 0) {
+    const node = worklist.pop();
+
+    if (!node || typeof node !== "object" || seen.has(node)) {
+      continue;
+    }
+    seen.add(node);
+
+    if (
+      node.type === "CallExpression" &&
+      node.callee.type === "Identifier" &&
+      node.callee.name === "registerCommand"
+    ) {
+      registerCommandCalled = true;
+      for (const arg of node.arguments) {
+        if (arg.type === "ObjectExpression") {
+          for (const prop of arg.properties) {
+            if (
+              prop.type === "Property" &&
+              prop.key.type === "Identifier" &&
+              prop.key.name === "transport" &&
+              prop.value.type === "Literal" &&
+              typeof prop.value.value === "string"
+            ) {
+              return prop.value.value;
+            }
+          }
+        }
+      }
+    }
+
+    switch (node.type) {
+      case "ExpressionStatement":
+        worklist.push(node.expression);
+        break;
+      case "CallExpression":
+        // Enqueue both arguments AND the callee so chained patterns like
+        // `registerCommand(...).command(...).description(...)` are walked.
+        // The outer call's callee is a MemberExpression whose object is the
+        // inner CallExpression; without traversing the callee we'd never
+        // reach the inner `registerCommand` invocation and findTransport()
+        // would return null, silently skipping all checks.
+        worklist.push(node.callee);
+        for (const arg of node.arguments) {
+          worklist.push(arg);
+        }
+        break;
+      case "MemberExpression":
+        // Reach through `.foo` chains so we can walk into the receiver.
+        worklist.push(node.object);
+        break;
+      case "FunctionDeclaration":
+      case "FunctionExpression":
+      case "ArrowFunctionExpression":
+        if (node.body) worklist.push(node.body);
+        break;
+      case "BlockStatement":
+        for (const stmt of node.body) {
+          worklist.push(stmt);
+        }
+        break;
+      case "ReturnStatement":
+        if (node.argument) worklist.push(node.argument);
+        break;
+      case "ExportNamedDeclaration":
+      case "ExportDefaultDeclaration":
+        if (node.declaration) worklist.push(node.declaration);
+        break;
+      case "VariableDeclaration":
+        for (const decl of node.declarations) {
+          if (decl.init) worklist.push(decl.init);
+        }
+        break;
+      case "ObjectExpression":
+        for (const prop of node.properties) {
+          if (prop.type === "Property") {
+            worklist.push(prop.value);
+          }
+        }
+        break;
+      default:
+        break;
+    }
+  }
+
+  return registerCommandCalled ? "MISSING_TRANSPORT" : null;
+}
+
+const rule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Enforce import allowlists for CLI commands by transport class",
+    },
+    messages: {
+      missingTransport:
+        "CLI command file must call registerCommand({ transport: ... }) to declare its transport class.",
+      forbiddenImport:
+        "'{{transport}}'-tagged CLI command imports forbidden module '{{source}}'. See src/cli/AGENTS.md for allowed imports.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const importNodes = [];
+
+    return {
+      ImportDeclaration(node) {
+        importNodes.push(node);
+      },
+
+      "Program:exit"(program) {
+        if (importNodes.length === 0) {
+          return;
+        }
+
+        const transport = findTransport(program);
+
+        // Helper modules (no registerCommand call) are not command entries —
+        // skip them. Command files that call registerCommand without a string
+        // transport prop still trip missingTransport.
+        if (transport === null) {
+          return;
+        }
+
+        if (transport === "MISSING_TRANSPORT") {
+          context.report({
+            node: program,
+            messageId: "missingTransport",
+          });
+          return;
+        }
+
+        const allowedPrefixes = ALLOWED_PREFIXES[transport];
+        if (!allowedPrefixes) {
+          return;
+        }
+
+        for (const importNode of importNodes) {
+          // `import type {...}` is erased at compile time — top-level type
+          // import kind is set to "type" on the declaration. Skip.
+          if (importNode.importKind === "type") {
+            continue;
+          }
+          // Inline-type form `import { type X, type Y } from "..."` keeps
+          // the declaration `importKind === "value"` while marking each
+          // ImportSpecifier with `importKind === "type"`. When *every*
+          // specifier is type-only the entire import is erased. Skip those
+          // too. Side-effect-only imports (`import "x"`) have an empty
+          // specifiers list and run at module load — must NOT skip.
+          if (
+            importNode.specifiers.length > 0 &&
+            importNode.specifiers.every(
+              (s) => s.type === "ImportSpecifier" && s.importKind === "type",
+            )
+          ) {
+            continue;
+          }
+          const source = importNode.source.value;
+          const allowed = allowedPrefixes.some((prefix) =>
+            source.startsWith(prefix),
+          );
+          if (!allowed) {
+            context.report({
+              node: importNode,
+              messageId: "forbiddenImport",
+              data: {
+                transport,
+                source,
+              },
+            });
+          }
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/eslint.config.mjs

@@ -2,6 +2,8 @@ import { defineConfig, globalIgnores } from "eslint/config";
 import simpleImportSort from "eslint-plugin-simple-import-sort";
 import tseslint from "typescript-eslint";
 
+import cliNoDaemonInternals from "./eslint-rules/cli-no-daemon-internals.js";
+
 const eslintConfig = defineConfig([
   ...tseslint.configs.recommended,
   globalIgnores(["dist/**", "drizzle/**"]),
@@ -43,6 +45,16 @@ const eslintConfig = defineConfig([
       "@typescript-eslint/no-explicit-any": "off",
     },
   },
+  // `cli/no-daemon-internals` enforces the CLI ↔ daemon import boundary
+  // that the CLI → IPC refactor is built on. Keep at `"error"`: a soft
+  // rule here would let daemon-internal imports re-enter the CLI bundle,
+  // which is the regression class this rule exists to prevent.
+  {
+    files: ["src/cli/commands/**/*.ts"],
+    ignores: ["src/cli/commands/**/__tests__/**"],
+    plugins: { cli: { rules: { "no-daemon-internals": cliNoDaemonInternals } } },
+    rules: { "cli/no-daemon-internals": "error" },
+  },
 ]);
 
 export default eslintConfig;

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"),

package/knip.json

@@ -3,7 +3,8 @@
     "src/**/*.test.ts",
     "src/**/__tests__/**/*.ts",
     "scripts/**/*.ts",
-    "src/daemon/main.ts!"
+    "src/daemon/main.ts!",
+    "src/plugin-api/index.ts!"
   ],
   "project": ["src/**/*.ts!", "src/**/*.tsx!", "scripts/**/*.ts"],
   "ignoreDependencies": [

package/node_modules/@vellumai/skill-host-contracts/src/client.ts

@@ -568,7 +568,16 @@ export class SkillHostClient implements SkillHost {
         params: { filter: fresh.filter },
       });
     } catch (err) {
-      this.cancelSubscribeAck(fresh);
+      // Drop only the pending ack and leave `fresh` registered. If the
+      // socket dropped between `doConnect()` and this write, the close
+      // handler will trigger another reconnect — and that cycle iterates
+      // `subscriptions`, so we must NOT remove or dispose `fresh` here
+      // or the stream is silently lost (autoReconnect contract).
+      const entry = this.pending.get(fresh.id);
+      if (entry) {
+        clearTimeout(entry.timer);
+        this.pending.delete(fresh.id);
+      }
       swallow(err);
     }
   }