@vellumai/assistant 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

package/docs/plugins.md

@@ -1,836 +0,0 @@
-# Plugins
-
-> **Note:** This guide documents the **legacy** plugin architecture — the
-> in-tree `register.ts` + middleware-pipeline system. We are converging on
-> the schema at
-> [`experimental/plugins/README.md`](../../experimental/plugins/README.md)
-> (file-based discovery, a `package.json` manifest, the
-> `@vellumai/plugin-api` public contract). The plan is to reshape this guide
-> section by section until it matches that one; wherever the two still
-> differ is the next piece of consolidation work. New plugins should target
-> the modern schema.
-
-Plugins extend the assistant's default capabilities using hooks, tools,
-skills, and more.
-
-If you're authoring a plugin against the current convention, this file is
-your map. Read [`examples/plugins/echo/`](../examples/plugins/echo/README.md)
-alongside, it's the canonical reference implementation and exercises every
-wired surface.
-
-## Table of contents
-
-- [TL;DR](#tldr)
-- [What a plugin can contribute today](#what-a-plugin-can-contribute-today)
-- [Anatomy of a plugin](#anatomy-of-a-plugin)
-- [Where plugins live](#where-plugins-live)
-- [Manifest](#manifest)
-- [Registration](#registration)
-- [Middleware patterns](#middleware-patterns)
-- [Pipeline reference](#pipeline-reference)
-- [Timeouts](#timeouts)
-- [Strict-fail semantics](#strict-fail-semantics)
-- [Credentials and config](#credentials-and-config)
-- [Tool, route, and skill contributions](#tool-route-and-skill-contributions)
-- [Cross-plugin communication](#cross-plugin-communication)
-- [Hot reload](#hot-reload)
-- [Troubleshooting](#troubleshooting)
-
----
-
-## TL;DR
-
-1. Create a directory `<workspaceDir>/plugins/my-plugin/`.
-2. Drop a `package.json` with a `name` and a `peerDependencies["@vellumai/plugin-api"]` semver range.
-3. Add `middlewares/<name>.ts` files (default export = middleware function).
-4. Add `tools/<name>.ts` files (default export = tool definition).
-5. Restart the assistant — the loader scans `<workspaceDir>/plugins/*` and
-   registers the plugin on startup.
-
-## What a plugin can contribute today
-
-| Surface                 | Where                     | Discovery                                         |
-| ----------------------- | ------------------------- | ------------------------------------------------- |
-| Pipeline middleware     | `plugin.middleware`       | keyed by pipeline name in `PipelineMiddlewareMap` |
-| Model-visible tools     | `plugin.tools`            | each `PluginToolRegistration`                     |
-| HTTP routes             | `plugin.routes`           | each `PluginRouteRegistration`                    |
-| Skills                  | `plugin.skills`           | each `PluginSkillRegistration`                    |
-| System-prompt injectors | `plugin.injectors`        | each `Injector`                                   |
-| Lifecycle               | `init()` / `onShutdown()` | methods on the `Plugin` object                    |
-
-The modern schema wires only **hooks** and **tools**; the middleware
-pipelines, routes, skills, and injectors above are the surfaces that still
-have no modern equivalent.
-
----
-
-## Anatomy of a plugin
-
-A plugin is a directory that exports a single `register.ts` (or compiled
-`register.js`) entry point. That file builds a `Plugin` object and passes
-it to `registerPlugin()` as an import-time side effect. Everything else —
-pipeline middleware, lifecycle hooks, model-visible capabilities — hangs
-off that one `Plugin` object.
-
-```
-my-plugin/
-├── package.json      # Node/Bun package metadata
-├── README.md         # optional — human docs
-└── register.ts       # the entry point the assistant imports
-```
-
-The `Plugin` shape is declared in
-[`assistant/src/plugins/types.ts`](../src/plugins/types.ts):
-
-```typescript
-export interface Plugin {
-  manifest: PluginManifest;
-  init?(ctx: PluginInitContext): Promise<void>;
-  onShutdown?(): Promise<void>;
-  tools?: PluginToolRegistration[];
-  routes?: PluginRouteRegistration[];
-  skills?: PluginSkillRegistration[];
-  injectors?: Injector[];
-  middleware?: Partial<PipelineMiddlewareMap>;
-}
-```
-
-Every field except `manifest` is optional. A plugin that only contributes
-middleware doesn't need tools or routes; a plugin that only contributes a
-skill can omit middleware entirely.
-
-## Where plugins live
-
-The assistant scans `<workspaceDir>/plugins/*` at startup. Any subdirectory
-containing `register.js` or `register.ts` is dynamic-imported once. The
-loader lives in
-[`assistant/src/plugins/user-loader.ts`](../src/plugins/user-loader.ts) and
-has three key properties:
-
-- **Compiled wins.** If both `register.js` and `register.ts` are present,
-  the compiled `.js` file is loaded. This matches how the compiled
-  assistant binary resolves modules in production.
-- **Per-plugin isolation.** If one plugin throws at import time, the error
-  is logged with the plugin directory and the loader moves on. Other
-  plugins still load. One broken plugin cannot brick the assistant.
-- **Per-instance.** The scan runs under `vellumRoot()`. Each assistant
-  instance loads its own plugin set.
-
-The loader runs after first-party plugin registrations and before
-`bootstrapPlugins()` invokes every plugin's `init()`.
-
-## Manifest
-
-The manifest is static metadata validated by the registry at registration
-time. Its shape (see
-[`types.ts`](../src/plugins/types.ts)):
-
-```typescript
-export interface PluginManifest {
-  name: string; // kebab-case, unique
-  version: string; // semver, informational
-  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>
-}
-```
-
-| 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.                                                                                                                                                |
-| `version`            | yes      | Plugin's own semver. Informational — the registry does not compare it.                                                                                                                                                                                                                                         |
-| `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()`.                                                                                                            |
-
-### Host-compat: `peerDependencies["@vellumai/plugin-api"]`
-
-Plugins declare which assistant versions they support via standard
-`peerDependencies` in their `package.json`:
-
-```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
-
-```typescript
-const manifest: PluginManifest = {
-  name: "my-logger",
-  version: "1.2.3",
-  requiresCredential: ["LOGGER_API_KEY"],
-  requiresFlag: ["my-logger-enabled"],
-  config: z.object({
-    endpoint: z.string().url(),
-    sampleRate: z.number().min(0).max(1).default(0.1),
-  }),
-};
-```
-
-### Feature-flag gating
-
-`manifest.requiresFlag` lists one or more **assistant-scope** feature-flag
-keys (the same keys declared in
-`meta/feature-flags/feature-flag-registry.json`). The bootstrap checks each
-key against `isAssistantFeatureFlagEnabled` before touching the plugin. If
-**any** listed flag is disabled, the plugin is skipped entirely for the
-duration of this assistant boot:
-
-- `init()` is **not** invoked.
-- `tools`, `routes`, and `skills` are **not** registered.
-- No shutdown hook entry is installed, so a plugin skipped at boot has
-  nothing to tear down on shutdown.
-
-Flag state is resolved once at bootstrap time. Flipping a `requiresFlag`
-key at runtime does not hot-reload the plugin — restart the assistant
-after changing the flag to pick up the new state. An empty `requiresFlag` (or
-the field being absent) means the plugin activates unconditionally.
-
-The skip path emits a single `info`-level log line naming both the plugin
-and the disabled flag, so operators can diagnose "why isn't my plugin
-loading?" at a glance:
-
-```
-plugins-bootstrap skipping plugin my-logger: feature flag my-logger-enabled is disabled
-```
-
-**Cross-repo note:** new flag keys used here must be declared in the
-assistant-scope section of
-`meta/feature-flags/feature-flag-registry.json` (and provisioned in the
-platform's Terraform configuration). See the root `CLAUDE.md`'s "Assistant
-Feature Flags" section for the full procedure.
-
-## Registration
-
-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 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",
-  },
-  middleware: {
-    /* ... */
-  },
-};
-
-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
-  duplicate names.
-- `register.ts` must not export named symbols consumed from outside. The
-  loader treats the import as side-effect-only.
-- Throwing inside `register.ts` is caught by the loader and logged, then
-  the loader moves on. Do not rely on throws to signal "please don't load
-  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
-
-Middleware is the heart of the plugin system. Every pipeline slot uses the
-same onion-style signature:
-
-```typescript
-export type Middleware<A, R> = (
-  args: A,
-  next: (args: A) => Promise<R>,
-  ctx: TurnContext,
-) => Promise<R>;
-```
-
-The runner composes an array of middleware around a terminal handler. The
-first middleware sees the request first and the response last; the
-terminal runs at the innermost layer. See
-[`assistant/src/plugins/pipeline.ts`](../src/plugins/pipeline.ts) for the
-composition algorithm.
-
-Four common patterns emerge from that signature:
-
-### Observe-only
-
-Record something without changing the call. Call `next(args)` unchanged,
-return the result unchanged. Wrap the call in `try`/`finally` so your
-observer runs on both success and failure paths.
-
-```typescript
-const observer: Middleware<ToolExecuteArgs, ToolExecuteResult> =
-  async function observeToolExecute(args, next, ctx) {
-    const start = performance.now();
-    let outcome: "success" | "error" = "success";
-    try {
-      return await next(args);
-    } catch (err) {
-      outcome = "error";
-      throw err;
-    } finally {
-      const ms = Math.round(performance.now() - start);
-      console.error(JSON.stringify({ tool: args.name, ms, outcome }));
-    }
-  };
-```
-
-### Transform input
-
-Rewrite `args` before calling downstream. Useful for request shimming
-(adding headers, redacting inputs, picking a different provider).
-
-```typescript
-const addHeader: Middleware<LLMCallArgs, LLMCallResult> =
-  async function addHeader(args, next, ctx) {
-    const tagged = {
-      ...args,
-      options: {
-        ...args.options,
-        config: { ...args.options?.config, requestId: ctx.requestId },
-      },
-    };
-    return next(tagged);
-  };
-```
-
-### Transform output
-
-Call `next(args)` first, then modify the result before returning.
-
-```typescript
-const redactPII: Middleware<LLMCallArgs, LLMCallResult> =
-  async function redactPII(args, next, ctx) {
-    const response = await next(args);
-    return {
-      ...response,
-      content: response.content.map(redactBlock),
-    };
-  };
-```
-
-### Short-circuit
-
-Do not call `next(args)` — return a synthetic result directly. The
-terminal and any inner middleware are skipped. Use this to stub, cache,
-or mock a pipeline.
-
-```typescript
-const cacheHit: Middleware<LLMCallArgs, LLMCallResult> =
-  async function cacheHit(args, next, ctx) {
-    const cached = await lookupCache(args);
-    if (cached) return cached;
-    return next(args);
-  };
-```
-
-### Veto (throw)
-
-Throwing from middleware aborts the pipeline. The error propagates out
-through any outer middleware unchanged — there is no internal
-`try`/`catch` around user middleware.
-
-```typescript
-const denyIfUnauthorized: Middleware<ToolExecuteArgs, ToolExecuteResult> =
-  async function denyIfUnauthorized(args, next, ctx) {
-    if (!isAuthorizedFor(args.name, ctx.trust)) {
-      throw new Error(`tool ${args.name} denied by policy`);
-    }
-    return next(args);
-  };
-```
-
-### Naming middleware
-
-Give middleware a stable `name` (via `async function <name>(…)`). The
-pipeline runner pulls `Function.name` into its `chain` log field so
-operators can see the registered chain at a glance:
-
-```
-plugin.pipeline pipeline=llmCall chain=["observeLlm","addHeader","defaultLlmCall"] durationMs=1840 outcome=success
-```
-
-## Pipeline reference
-
-Every pipeline slot and its purpose. Type details live in
-[`types.ts`](../src/plugins/types.ts).
-
-| Pipeline             | Purpose                                                                                                                                            |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `turn`               | The outermost wrapper around a single assistant turn. Middleware here sees everything a turn does end-to-end.                                      |
-| `llmCall`            | Every call to `Provider.sendMessage`. Input carries `messages` and `options` (with `tools`, `systemPrompt`, `config`, `onEvent`, `signal` inside). |
-| `toolExecute`        | Every `ToolExecutor.execute` call. Input carries `name`, `input`, and the full `ToolContext`.                                                      |
-| `memoryRetrieval`    | PKB, NOW.md, and memory-graph retrieval for a turn. Output is a merged `MemoryResult`.                                                             |
-| `historyRepair`      | The pre-run repair pass on the message history. Wraps `repairHistory`.                                                                             |
-| `tokenEstimate`      | The token-count estimate used for budgeting. Wraps `estimatePromptTokensRaw`.                                                                      |
-| `compaction`         | The conversation-compaction step. Wraps `ContextWindowManager.maybeCompact`.                                                                       |
-| `overflowReduce`     | The reducer tier loop invoked when a turn blows the context budget.                                                                                |
-| `persistence`        | Every message CRUD op (`add` / `update` / `delete`). Discriminated by `args.op`.                                                                   |
-| `titleGenerate`      | Conversation title generation. Fire-and-forget by default.                                                                                         |
-| `toolResultTruncate` | The per-tool-result truncation step that fits a tool's output into the context window.                                                             |
-| `emptyResponse`      | The decision about what to do when the model returns an empty turn (nudge / accept / error).                                                       |
-| `toolError`          | The decision about what to do when one or more tool calls errored on a turn.                                                                       |
-| `circuitBreaker`     | The compaction circuit breaker. Tracks consecutive-failure state, decides whether to open the circuit.                                             |
-
-## Timeouts
-
-Each pipeline has a default timeout budget in milliseconds. When the
-budget is exceeded the runner throws `PluginTimeoutError` carrying the
-pipeline name, the offending plugin's name (if known), and the elapsed
-duration. See
-[`assistant/src/plugins/pipeline.ts`](../src/plugins/pipeline.ts) for the
-current values.
-
-| Pipeline             | Timeout  | Rationale                                                                                                      |
-| -------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
-| `turn`               | none     | Turn duration is bounded by the downstream `llmCall` / `toolExecute` timeouts, not a pipeline-level timer.     |
-| `llmCall`            | none     | Deferred to the provider's HTTP timeout so network hiccups surface as provider errors, not pipeline timeouts.  |
-| `toolExecute`        | none     | Deferred to the per-tool timeout already enforced by `ToolExecutor`.                                           |
-| `memoryRetrieval`    | 5000 ms  | Memory reads may hit Qdrant and disk; 5 s leaves slack for cold caches without blocking the turn indefinitely. |
-| `historyRepair`      | 1000 ms  | CPU-bound list walk — should finish in a few ms.                                                               |
-| `tokenEstimate`      | 1000 ms  | Same — CPU-bound, should return instantly.                                                                     |
-| `compaction`         | 30000 ms | Summarization involves a provider call; mirrors the pipeline-level budget for LLM-backed operations.           |
-| `overflowReduce`     | 30000 ms | Iterative compaction; matches the `compaction` budget since each tier step may invoke it.                      |
-| `persistence`        | 10000 ms | SQLite writes, Qdrant deletes, and disk syncs. 10 s is generous for the slowest op (batched segment inserts).  |
-| `titleGenerate`      | 30000 ms | Provider-backed. Fire-and-forget, but the budget exists so a stuck call doesn't leak forever.                  |
-| `toolResultTruncate` | 1000 ms  | Pure string op.                                                                                                |
-| `emptyResponse`      | 500 ms   | Decision logic only — must be near-instant.                                                                    |
-| `toolError`          | 500 ms   | Decision logic only — must be near-instant.                                                                    |
-| `circuitBreaker`     | 500 ms   | Numeric state update — must be near-instant.                                                                   |
-
-`null` timeouts skip the timer entirely. Finite timeouts arm a
-`setTimeout` that races the pipeline via `Promise.race`.
-
-## Strict-fail semantics
-
-**Plugin errors and timeouts fail the turn loudly. There is no silent
-fallback to the default behavior.**
-
-This is a deliberate design decision. The old inline behavior silently
-absorbed many edge cases (a memory retrieval failure became an empty
-memory block, a compaction error became no compaction, etc.). That made
-debugging production issues miserable because failures disappeared into
-logs nobody checked.
-
-With strict-fail:
-
-- Any error thrown from middleware propagates up to the caller. The
-  pipeline runner does not catch it.
-- Any `PluginTimeoutError` from a budget breach propagates identically.
-- The caller (agent loop, memory subsystem, whoever) decides how to
-  degrade. The pipeline itself does not paper over the failure.
-- Exactly one structured log line is emitted per pipeline invocation, in
-  a `finally` block, regardless of outcome. It carries `outcome`
-  (`"success" | "error" | "timeout"`), `durationMs`, `chain`, plugin
-  attribution, and error details when applicable.
-
-If you're writing middleware that wants to "try, fall back to default on
-failure," express that at the call site instead — wrap the pipeline
-invocation in your own try/catch. Do not swallow the error inside your
-middleware's `try`/`catch` and silently return a degraded result.
-
-## Credentials and config
-
-### Credentials
-
-Declare required credential keys in `manifest.requiresCredential`:
-
-```typescript
-const manifest: PluginManifest = {
-  name: "my-plugin",
-  version: "1.0.0",
-  requiresCredential: ["MY_PLUGIN_API_KEY"],
-};
-```
-
-During bootstrap, the assistant resolves each key through the credential
-store (via `getSecureKeyAsync`). In Docker mode that call goes through
-the CES HTTP API; in local mode it hits the encrypted file store / CES
-RPC backend. The resolved values are handed to your `init()`:
-
-```typescript
-async init(ctx: PluginInitContext) {
-  const apiKey = ctx.credentials["MY_PLUGIN_API_KEY"];
-  // use it
-}
-```
-
-**Rules:**
-
-- Never import the credential store directly. Always go through the
-  manifest.
-- Missing credentials fail startup with a clear error naming the plugin
-  and the key. There is no silent fallback.
-- Credentials are resolved once at bootstrap. Long-running plugins that
-  need rotation must re-resolve through their own mechanism.
-
-### Config
-
-Declare a parser-like validator in `manifest.config`:
-
-```typescript
-const configSchema = z.object({
-  endpoint: z.string().url(),
-  sampleRate: z.number().min(0).max(1).default(0.1),
-});
-
-const manifest: PluginManifest = {
-  name: "my-plugin",
-  version: "1.0.0",
-  config: configSchema,
-};
-```
-
-The bootstrap reads `config.plugins.<name>` from the assistant's config
-and calls `manifest.config.parse(raw)`. The parsed result is handed to
-your `init()`:
-
-```typescript
-async init(ctx: PluginInitContext) {
-  const cfg = ctx.config as z.infer<typeof configSchema>;
-  // use cfg
-}
-```
-
-If you don't supply a validator, the raw config is passed through
-untouched as `unknown` and your plugin must narrow it itself.
-
-### Other init context fields
-
-The full `PluginInitContext`:
-
-```typescript
-export interface PluginInitContext {
-  config: unknown; // parsed config (or raw if no validator)
-  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 — same value used by the loader
-  //                          against your peerDependencies range
-}
-```
-
-`pluginStorageDir` is a per-plugin writable directory. Use it for
-persistent state — cache files, counters, anything that must survive an
-assistant restart. The bootstrap creates it on demand.
-
-## Tool, route, and skill contributions
-
-Plugins can contribute model-visible capabilities alongside their
-middleware. Each is optional.
-
-### Tools (`plugin.tools`)
-
-An array of `Tool` objects. The bootstrap registers them with the global
-tool registry after `init()` succeeds, stamping `origin: "plugin"` and
-`owner: { kind: "plugin", id: <plugin.name> }` so they live in a ref-count
-namespace disjoint from real skills (a plugin whose `manifest.name`
-happens to match a skill id cannot collide with that skill's
-registrations).
-
-```typescript
-const myPlugin: Plugin = {
-  manifest: {
-    /* ... */
-  },
-  tools: [
-    {
-      name: "my_tool",
-      description: "Does the thing.",
-      category: "plugin",
-      defaultRiskLevel: "low",
-      getDefinition: () => ({
-        name: "my_tool",
-        description: "Does the thing.",
-        input_schema: { type: "object", properties: {}, required: [] },
-      }),
-      execute: async (input, ctx) => ({ content: "result", isError: false }),
-    },
-  ],
-};
-```
-
-Tools are unregistered automatically on shutdown. See
-[`assistant/src/tools/types.ts`](../src/tools/types.ts) for the full
-`Tool` interface including optional fields like `executionMode` and
-`executionTarget`.
-
-### Routes (`plugin.routes`)
-
-An array of `SkillRoute` objects — the same shape the skill-route
-registry consumes. Registered via `registerSkillRoute` after `init()`
-succeeds; the runtime retains the opaque handle returned by each call
-and uses those handles to unregister the plugin's routes on shutdown.
-Handle-keyed unregistration is deliberate: two owners (plugin vs.
-skill, or plugin vs. plugin) can legitimately declare the same regex,
-and identity matching ensures one owner's teardown cannot evict
-another owner's live routes.
-
-```typescript
-const myPlugin: Plugin = {
-  manifest: {
-    /* ... */
-  },
-  routes: [
-    {
-      pattern: /^\/_plugin\/my-plugin\/status$/,
-      methods: ["GET"],
-      handler: async (req, match) => new Response("ok"),
-    },
-  ],
-};
-```
-
-### Skills (`plugin.skills`)
-
-An array of `PluginSkillRegistration` objects. Each becomes a discoverable
-skill under `source: "plugin"` in the model's `skill_load` /
-`skill_execute` flow.
-
-```typescript
-const myPlugin: Plugin = {
-  manifest: {
-    /* ... */
-  },
-  skills: [
-    {
-      id: "my-plugin/do-thing",
-      name: "do-thing",
-      description: "Does the thing via plugin-contributed skill.",
-      body: "# SKILL.md body returned when loaded\n...",
-    },
-  ],
-};
-```
-
-See
-[`plugin-skill-contributions.ts`](../src/plugins/plugin-skill-contributions.ts)
-for the in-memory registry details and ref-counted lifecycle.
-
-### Injectors (`plugin.injectors`)
-
-An array of `Injector` objects that emit system-prompt-time content.
-Each has a stable `name`, an ascending `order` used to position it in the
-injection chain, and a `produce(ctx)` method that returns an
-`InjectionBlock` or `null`.
-
-The default injectors use `order` 10 through 70 with gaps of 10, so
-plugin-contributed injectors can slot at `25`, `35`, etc. without
-renumbering.
-
-```typescript
-const myPlugin: Plugin = {
-  manifest: {
-    /* ... */
-  },
-  injectors: [
-    {
-      name: "my-plugin/status",
-      order: 25,
-      async produce(ctx) {
-        return {
-          id: "my-plugin/status",
-          text: `<my_plugin_status>ok</my_plugin_status>`,
-        };
-      },
-    },
-  ],
-};
-```
-
-## Cross-plugin communication
-
-Plugins should not call each other directly. There is no cross-plugin
-import API — a plugin's export surface is intentionally limited to the
-`Plugin` object it registers.
-
-For cross-cutting concerns (broadcasting events, reacting to
-system-level changes), use the `assistantEventHub` pub/sub in
-[`runtime/assistant-event-hub.ts`](../src/runtime/assistant-event-hub.ts).
-The hub is the canonical place to publish events from inside the
-assistant process and to subscribe from anywhere that has access to the
-assistant's module graph.
-
-Do not add new HTTP endpoints to implement plugin-to-plugin messaging
-inside a single assistant process.
-
-## Hot reload
-
-**Not supported in v1.** Registering a plugin takes effect at assistant
-startup only. To pick up a new or modified plugin:
-
-```bash
-vellum restart
-```
-
-The registry's internal state is not mutable at runtime. `init()` and
-`onShutdown()` hooks are fired exactly once per assistant boot.
-
-If you need hot reload for development, symlink your plugin directory
-into `<workspaceDir>/plugins/` so edits propagate, and automate the restart
-loop externally.
-
-## Troubleshooting
-
-### `external plugin X: peerDependencies["@vellumai/plugin-api"] requires "<range>" but assistant is <version> — loading anyway`
-
-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.
-
-### `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.
-
-### `external plugin X missing plugin-api peerDependency — loading without host-compat claim`
-
-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"
-
-Two plugins tried to register under the same `manifest.name`. Names must
-be globally unique. Rename one, or if this is a dev-reload issue,
-restart the assistant.
-
-### "plugin X requires credential Y but the credential store returned no value"
-
-The credential named in `requiresCredential` is not set. Run:
-
-```bash
-vellum credentials set Y
-```
-
-…and restart the assistant.
-
-### "plugin X config validation failed: …"
-
-The config block under `config.plugins.<name>` failed the manifest's
-parser. Check your config against the plugin's schema — the error
-message carries the validator's diagnostic.
-
-### `PluginTimeoutError: Plugin pipeline '<name>' timed out after N ms`
-
-A plugin's middleware exceeded the pipeline's budget. The offending
-plugin is named in `ctx.pluginName` when available. Tighten the
-middleware (it's probably blocking on I/O it shouldn't) or, if the
-work is genuinely heavy, move it out of the critical path into a
-background job that publishes results through `assistantEventHub`.
-
-### Reading pipeline log records
-
-Every pipeline invocation emits one structured line tagged
-`event=plugin.pipeline`. The fields:
-
-| Field                                      | Meaning                                                                 |
-| ------------------------------------------ | ----------------------------------------------------------------------- |
-| `pipeline`                                 | Pipeline name (`llmCall`, `toolExecute`, …).                            |
-| `chain`                                    | Ordered list of middleware function names, outermost first.             |
-| `durationMs`                               | Total time spent in the composed chain.                                 |
-| `outcome`                                  | `"success"`, `"error"`, or `"timeout"`.                                 |
-| `pluginName`                               | The specific plugin's name when the runner could attribute the frame.   |
-| `timeoutMs`                                | The configured budget (only when one was set).                          |
-| `errorName`, `errorMessage`, `errorStack`  | Present on failure outcomes.                                            |
-| `requestId`, `conversationId`, `turnIndex` | Per-turn context for correlating with the rest of the assistant's logs. |
-
-Pipe the assistant's stderr through `jq` to filter and inspect:
-
-```bash
-tail -f ~/.vellum/daemon.log | jq 'select(.event == "plugin.pipeline")'
-```
-
-To isolate slow pipelines:
-
-```bash
-tail -f ~/.vellum/daemon.log \
-  | jq 'select(.event == "plugin.pipeline" and .durationMs > 1000)'
-```
-
-To isolate errors and timeouts:
-
-```bash
-tail -f ~/.vellum/daemon.log \
-  | jq 'select(.event == "plugin.pipeline" and .outcome != "success")'
-```
-
-### Plugin not loading at all
-
-- Confirm the directory is under `<workspaceDir>/plugins/`.
-- Confirm it has a `register.ts` or `register.js` at the top level.
-- Check the assistant's stderr for a line like
-  `loaded user plugin (side-effect import completed)` or
-  `Failed to load user plugin <dir>: <err>`. Import-time throws are
-  logged but do not crash the assistant — the plugin is silently skipped
-  otherwise.
-- Verify `register.ts` calls `registerPlugin()` exactly once at module
-  level. If the call is inside an unrelated conditional or wrapped in
-  an async function that is never awaited, the registry won't see it.