@vellumai/assistant 0.8.6 → 0.8.7-dev.202606052135.3e62c5a

package/docs/plugins.md

@@ -1,25 +1,32 @@
-# Plugin authoring guide
-
-Plugins let you extend the assistant by hooking middleware into named
-runtime pipelines, contributing tools/routes/skills, and injecting
-system-prompt content. This guide is the authoritative reference for how
-plugins are structured, registered, and executed — everything the code
-actually enforces.
-
-For a worked minimal example, see
-[`assistant/examples/plugins/echo/`](../examples/plugins/echo/README.md).
-That plugin observes every pipeline and logs to stderr, and is the fastest
-way to see the system in action.
+# Plugins
+
+> **Note:** This guide documents the **legacy** plugin architecture — the
+> in-tree `register.ts` registration 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)
+- [Hooks](#hooks)
 - [Strict-fail semantics](#strict-fail-semantics)
 - [Credentials and config](#credentials-and-config)
 - [Tool, route, and skill contributions](#tool-route-and-skill-contributions)
@@ -29,13 +36,36 @@ way to see the system in action.
 
 ---
 
+## 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 `hooks/<name>.ts` files (default export = hook 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                                  |
+| -------------------------- | --------------- | ------------------------------------------ |
+| Model-visible tools        | `plugin.tools`  | each `PluginToolRegistration`              |
+| HTTP routes                | `plugin.routes` | each `PluginRouteRegistration`             |
+| Skills                     | `plugin.skills` | each `PluginSkillRegistration`             |
+| Lifecycle & per-turn hooks | `plugin.hooks`  | keyed by hook name (`init`, `shutdown`, …) |
+
+The modern schema wires only **hooks** and **tools**; routes and skills
+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.
+lifecycle hooks, model-visible capabilities — hangs off that one `Plugin`
+object.
 
 ```
 my-plugin/
@@ -50,19 +80,17 @@ The `Plugin` shape is declared in
 ```typescript
 export interface Plugin {
   manifest: PluginManifest;
-  init?(ctx: PluginInitContext): Promise<void>;
-  onShutdown?(): Promise<void>;
-  tools?: PluginToolRegistration[];
+  hooks?: PluginHooks;
+  tools?: Tool[];
   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.
+a hook doesn't need tools or routes; a plugin that only contributes a
+skill can omit everything else. Lifecycle and per-turn behavior live under
+`hooks` (see [Hooks](#hooks)).
 
 ## Where plugins live
 
@@ -220,7 +248,7 @@ const myPlugin: Plugin = {
     name: "my-plugin",
     version: "0.1.0",
   },
-  middleware: {
+  hooks: {
     /* ... */
   },
 };
@@ -256,180 +284,31 @@ and they have no module-identity effect at runtime.
 - 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.
+## Hooks
 
-```typescript
-const redactPII: Middleware<LLMCallArgs, LLMCallResult> =
-  async function redactPII(args, next, ctx) {
-    const response = await next(args);
-    return {
-      ...response,
-      content: response.content.map(redactBlock),
-    };
-  };
-```
+Hooks are the **modern** lifecycle surface: a plugin contributes one
+function per phase under `plugin.hooks`, keyed by hook name. The wired
+hook names live in [`HOOKS`](../src/plugin-api/constants.ts); the context
+shapes and a full authoring walkthrough live in the
+[experimental plugin guide](../../experimental/plugins/README.md#hooks).
 
-### 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);
-  };
-```
+Every hook implements `PluginHookFn` — it receives a context and either
+mutates it in place (returning `void`) or returns a replacement. Hooks
+from multiple plugins chain in registration order, and defaults register
+first.
 
-### 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`, `tools`, `systemPrompt`, `options`.           |
-| `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`.
+| Hook                 | Fires                                                             | Context                   |
+| -------------------- | ----------------------------------------------------------------- | ------------------------- |
+| `init`               | Once when the plugin is registered.                               | `PluginInitContext`       |
+| `shutdown`           | Once when the plugin is torn down.                                | `PluginShutdownContext`   |
+| `user-prompt-submit` | Once per user turn, before the agent loop receives the messages.  | `UserPromptSubmitContext` |
+| `post-tool-use`      | Once per tool result, before it joins the provider-bound history. | `PostToolUseContext`      |
+| `stop`               | Once per run when the model yields a turn with no tool calls.     | `StopContext`             |
 
 ## Strict-fail semantics
 
-**Plugin errors and timeouts fail the turn loudly. There is no silent
-fallback to the default behavior.**
+**Plugin errors 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
@@ -439,20 +318,15 @@ 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.
+- Any error thrown from a hook propagates up to the caller. The hook
+  runner does not catch it.
 - 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
+  degrade. The runner itself does not paper over the failure.
+
+If you're writing a hook that wants to "try, fall back to default on
+failure," express that at the call site instead — wrap the hook
 invocation in your own try/catch. Do not swallow the error inside your
-middleware's `try`/`catch` and silently return a degraded result.
+hook's `try`/`catch` and silently return a degraded result.
 
 ## Credentials and config
 
@@ -542,7 +416,7 @@ 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.
+hooks. Each is optional.
 
 ### Tools (`plugin.tools`)
 
@@ -632,37 +506,6 @@ 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
@@ -743,50 +586,6 @@ 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/`.

package/examples/plugins/echo/README.md

@@ -1,32 +1,30 @@
 # Echo plugin
 
-Minimal example plugin. Observes every assistant pipeline and logs one JSON
-line per invocation to `stderr`:
+Minimal example plugin. Observes the assistant's turn-lifecycle hooks and logs
+one JSON line per hook invocation to `stderr`:
 
 ```json
-{"plugin":"echo","pipeline":"toolExecute","durationMs":42,"outcome":"success"}
-{"plugin":"echo","pipeline":"llmCall","durationMs":1873,"outcome":"success"}
+{
+  "plugin": "echo",
+  "hook": "post-tool-use",
+  "conversationId": "conv_abc123"
+}
 ```
 
 Use this as a starting point for writing your own plugin, or as a quick way
-to eyeball which pipelines fire during a conversation and how long they
-take.
+to eyeball which hooks fire during a conversation.
 
 For the full plugin authoring guide, see
 [`assistant/docs/plugins.md`](../../../docs/plugins.md).
 
 ## What it does
 
-- Registers one observer middleware per slot in
-  `PipelineMiddlewareMap` — `turn`, `llmCall`, `toolExecute`,
-  `memoryRetrieval`, `historyRepair`, `tokenEstimate`, `compaction`,
-  `overflowReduce`, `persistence`, `titleGenerate`, `toolResultTruncate`,
-  `emptyResponse`, `toolError`, and `circuitBreaker`.
-- Each middleware calls `next(args)` to pass the request through unchanged,
-  measures wall-clock duration, and emits one line to `stderr` whether the
-  downstream succeeded or threw.
-- Never modifies arguments, never rewrites results, never swallows errors.
-  It is purely observational — safe to stack alongside any other plugin.
+- Registers one observer hook per turn-lifecycle event:
+  `user-prompt-submit`, `post-tool-use`, and `stop`.
+- Each hook emits one line to `stderr` and returns `void`, so the threaded
+  context flows through unchanged.
+- Never modifies the turn's messages, tool results, or stop decision. It is
+  purely observational — safe to stack alongside any other plugin.
 
 ## Install locally
 
@@ -86,28 +84,23 @@ vellum restart
 ## Verify it works
 
 With the plugin installed and the assistant restarted, send any message
-that exercises a pipeline — a conversation turn, a tool call, a title
-generation — and tail the assistant's stderr log:
+that exercises a turn — a conversation reply, a tool call — and tail the
+assistant's stderr log:
 
 ```bash
 tail -f ~/.vellum/daemon.log
 ```
 
-You should see one line per pipeline invocation, similar to:
+You should see one line per hook invocation, similar to:
 
 ```json
-{"plugin":"echo","pipeline":"persistence","durationMs":3,"outcome":"success"}
-{"plugin":"echo","pipeline":"tokenEstimate","durationMs":1,"outcome":"success"}
-{"plugin":"echo","pipeline":"memoryRetrieval","durationMs":64,"outcome":"success"}
-{"plugin":"echo","pipeline":"historyRepair","durationMs":0,"outcome":"success"}
-{"plugin":"echo","pipeline":"llmCall","durationMs":1520,"outcome":"success"}
-{"plugin":"echo","pipeline":"turn","durationMs":1590,"outcome":"success"}
+{
+  "plugin": "echo",
+  "hook": "post-tool-use",
+  "conversationId": "conv_abc123"
+}
 ```
 
-If a pipeline throws (for example, a tool that errors out), you'll see a
-line with `"outcome":"error"` — the plugin rethrows after logging so the
-original error still propagates.
-
 ## Uninstall
 
 Remove the symlink (or the copied directory) and restart the assistant:
@@ -120,13 +113,11 @@ vellum restart
 ## Next steps
 
 - Read [`assistant/docs/plugins.md`](../../../docs/plugins.md) for the full
-  plugin authoring guide: manifest shape, middleware patterns
-  (observe / transform / short-circuit / veto), strict-fail semantics, the
-  per-pipeline timeout table, credential and config access, and
-  troubleshooting.
+  plugin authoring guide: manifest shape, hook patterns
+  (observe / transform), credential and config access, and troubleshooting.
 - Look at the first-party default plugins under
-  `assistant/src/plugins/defaults/` for examples of non-observational
-  middleware.
+  `assistant/src/plugins/defaults/` for examples of hooks that transform a
+  turn rather than just observing it.
 - Build your own plugin by copying this directory, renaming the manifest
-  `name`, and replacing the observer with a middleware that does whatever
-  you need.
+  `name`, and replacing the observer hooks with ones that do whatever you
+  need.