@vellumai/assistant 0.8.6 → 0.8.7-dev.202606052118.34cd356

package/AGENTS.md

@@ -78,15 +78,15 @@ When writing or updating comments, **do not reference code that has been removed
 
 ## Test machinery isolation
 
-**Test files and test helpers (anything under `__tests__/`) must not import from `src/` except for the production module they are testing.** No transitive imports from `src/` into helpers, preloads, or shared test utilities.
+**Test machinery — the test preload, the preload verifier, and shared test helpers — must not reach into `src/`.** Regular `*.test.ts` files may import production modules they exercise (the module under test, types, sibling utilities) like any normal consumer; the strict no-`src/` rule applies only to infrastructure that runs _before_ the per-test workspace override is established.
 
-The rule exists because test machinery and production code have **inverted invariants**: production assumes the workspace exists and is real; tests assume the workspace is a per-process temp dir that's safe to destroy. When a helper reaches into `src/` to set up state, it ties those invariants together — and a future change to either side can silently break the isolation the helper was supposed to provide. The May 2026 DB-ghost incidents (3 in 4 days) all traced back to test code touching production state through this kind of coupling.
+The rule exists because test machinery and production code have **inverted invariants**: production assumes the workspace exists and is real; tests assume the workspace is a per-process temp dir that's safe to destroy. When a _preload_ or _helper_ reaches into `src/` to set up state, it pulls in import-time side effects before the workspace override is set — and a future change to either side can silently break the isolation the helper was supposed to provide. The May 2026 DB-ghost incidents (3 in 4 days) all traced back to preload-time code touching production state through this kind of coupling. Per-test-file imports run after preload and inside the workspace override, so they don't have this problem.
 
 Concretely:
 
 - **Test helpers** (e.g. `src/__tests__/*-test-helpers.ts`) use only node stdlib, `bun:test`, and sibling helpers. If they need to manipulate shared state that production code also reads, both sides declare a typed slot under `globalThis.vellumAssistant.*` and read/write that slot independently. The slot shape is duplicated by design — the helper and the production module both reference the namespace, neither imports the other.
-- **The test preload** (`src/__tests__/test-preload.ts`) is even stricter: it must not import from `src/` at all. Its only static imports are node stdlib, `bun:test`, and helpers in `src/__tests__/`. Importing from a source module risks running its import-time side effects before the workspace override is set.
+- **The test preload** (`src/__tests__/test-preload.ts`) is the strictest: it must not import from `src/` at all. Its only static imports are node stdlib, `bun:test`, and helpers in `src/__tests__/`. Importing from a source module risks running its import-time side effects before the workspace override is set.
 - **The preload verifier** (`src/__tests__/test-preload-verifier.ts`) runs after the main preload and asserts the override took effect (`VELLUM_WORKSPACE_DIR` must resolve under `os.tmpdir()`).
 - **Destructive ops** (e.g. `rmSync(dbPath, ...)`) in tests must call `assertNotLiveDb(path)` from `src/__tests__/assert-not-live-db.js` immediately before the destructive call. The check is a per-callsite belt to the preload-verifier suspenders.
 
-When in doubt: **if a piece of test infrastructure can live in `__tests__/` without reaching into `src/`, it must.** Reach for source-code coupling only when there is no `__tests__/`-only alternative that achieves the same invariant.
+When in doubt: **if a piece of test infrastructure (preload / helper / verifier) can live in `__tests__/` without reaching into `src/`, it must.** Reach for source-code coupling only when there is no `__tests__/`-only alternative that achieves the same invariant. This restriction is about preload-time infrastructure, not the test files themselves.

package/Dockerfile

@@ -21,6 +21,7 @@ COPY packages/ces-client ./packages/ces-client
 COPY packages/service-contracts ./packages/service-contracts
 COPY packages/credential-storage ./packages/credential-storage
 COPY packages/egress-proxy ./packages/egress-proxy
+COPY packages/environments ./packages/environments
 COPY packages/gateway-client ./packages/gateway-client
 COPY packages/ipc-server-utils ./packages/ipc-server-utils
 COPY packages/skill-host-contracts ./packages/skill-host-contracts
@@ -76,6 +77,7 @@ RUN apt-get update && apt-get install -y \
     debootstrap \
     debian-archive-keyring \
     debconf \
+    e2fsprogs \
     ffmpeg \
     fonts-freefont-ttf \
     g++ \
@@ -112,11 +114,13 @@ RUN apt-get update && apt-get install -y \
     libxtst6 \
     lsof \
     make \
+    mount \
     openssl \
     procps \
     python3 \
     sqlite3 \
     sudo \
+    util-linux \
     unzip \
     uuid-runtime \
     vim \
@@ -179,7 +183,8 @@ RUN printf '%s\n' \
 RUN printf '%s\n' \
     '#!/usr/bin/env sh' \
     'set -eu' \
-    'if [ "${VELLUM_SANDBOX_RUNTIME:-}" != "kata" ]; then' \
+    '. /app/assistant/docker-kata-runtime-family.sh' \
+    'if ! vellum_is_kata_family_runtime; then' \
     '  exec /usr/bin/apt-get "$@"' \
     'fi' \
     'export DEBIAN_FRONTEND=noninteractive' \
@@ -194,7 +199,8 @@ RUN printf '%s\n' \
     printf '%s\n' \
     '#!/usr/bin/env sh' \
     'set -eu' \
-    'if [ "${VELLUM_SANDBOX_RUNTIME:-}" != "kata" ]; then' \
+    '. /app/assistant/docker-kata-runtime-family.sh' \
+    'if ! vellum_is_kata_family_runtime; then' \
     '  exec /usr/bin/apt "$@"' \
     'fi' \
     'export DEBIAN_FRONTEND=noninteractive' \
@@ -209,7 +215,8 @@ RUN printf '%s\n' \
     printf '%s\n' \
     '#!/usr/bin/env sh' \
     'set -eu' \
-    'if [ "${VELLUM_SANDBOX_RUNTIME:-}" != "kata" ]; then' \
+    '. /app/assistant/docker-kata-runtime-family.sh' \
+    'if ! vellum_is_kata_family_runtime; then' \
     '  exec /usr/bin/dpkg "$@"' \
     'fi' \
     'DATA_ROOT="${VELLUM_APT_DATA_ROOT:-/data/system}"' \
@@ -235,7 +242,17 @@ ENV IS_CONTAINERIZED=true
 # and the generated meet-join manifest from the builder stage.
 COPY --from=builder /app /app
 
-RUN chmod +x /app/assistant/docker-entrypoint.sh /app/assistant/docker-init-apt-root.sh /app/assistant/docker-kata-apt-env.sh
+COPY packages/block-volume-bootstrap/scripts/*.sh /usr/local/bin/
+
+RUN chmod +x \
+    /app/assistant/docker-entrypoint.sh \
+    /app/assistant/docker-init-apt-root.sh \
+    /app/assistant/docker-kata-apt-env.sh \
+    /app/assistant/docker-kata-runtime-family.sh \
+    /usr/local/bin/vellum-block-volume-common.sh \
+    /usr/local/bin/vellum-block-volume-init.sh \
+    /usr/local/bin/vellum-block-volume-mount.sh \
+    /usr/local/bin/vellum-block-volume-resize.sh
 
 # Run the daemon + http server
 CMD ["/app/assistant/docker-entrypoint.sh"]

package/bun.lock

@@ -5,18 +5,17 @@
     "": {
       "name": "@vellumai/assistant",
       "dependencies": {
-        "@agentclientprotocol/sdk": "0.16.1",
+        "@agentclientprotocol/sdk": "0.25.0",
         "@anthropic-ai/sdk": "0.78.0",
         "@google/genai": "1.45.0",
         "@modelcontextprotocol/sdk": "1.27.1",
         "@qdrant/js-client-rest": "1.17.0",
         "@resvg/resvg-js": "2.6.2",
-        "@resvg/resvg-js-darwin-arm64": "2.6.2",
-        "@resvg/resvg-js-darwin-x64": "2.6.2",
         "@sentry/node": "10.43.0",
         "@vellumai/ces-client": "file:../packages/ces-client",
         "@vellumai/credential-storage": "file:../packages/credential-storage",
         "@vellumai/egress-proxy": "file:../packages/egress-proxy",
+        "@vellumai/environments": "file:../packages/environments",
         "@vellumai/gateway-client": "file:../packages/gateway-client",
         "@vellumai/ipc-server-utils": "file:../packages/ipc-server-utils",
         "@vellumai/service-contracts": "file:../packages/service-contracts",
@@ -61,6 +60,10 @@
         "typescript": "5.9.3",
         "typescript-eslint": "8.57.0",
       },
+      "optionalDependencies": {
+        "@resvg/resvg-js-darwin-arm64": "2.6.2",
+        "@resvg/resvg-js-darwin-x64": "2.6.2",
+      },
     },
   },
   "overrides": {
@@ -68,7 +71,7 @@
     "path-to-regexp": "8.4.2",
   },
   "packages": {
-    "@agentclientprotocol/sdk": ["@agentclientprotocol/sdk@0.16.1", "", { "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" } }, "sha512-1ad+Sc/0sCtZGHthxxvgEUo5Wsbw16I+aF+YwdiLnPwkZG8KAGUEAPK6LM6Pf69lCyJPt1Aomk1d+8oE3C4ZEw=="],
+    "@agentclientprotocol/sdk": ["@agentclientprotocol/sdk@0.25.0", "", { "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" } }, "sha512-wU1VgXNtMvdVotX49txc3WJUDV+/QbLpsgjMvFhlRmp37osdLbI7L7y+iwAlQATwfjLxcv1r1p3ZxZBcXlGhcQ=="],
 
     "@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.78.0", "", { "dependencies": { "json-schema-to-ts": "^3.1.1" }, "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["zod"], "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-PzQhR715td/m1UaaN5hHXjYB8Gl2lF9UVhrrGrZeysiF6Rb74Wc9GCB8hzLdzmQtBd1qe89F9OptgB9Za1Ib5w=="],
 
@@ -424,6 +427,8 @@
 
     "@vellumai/egress-proxy": ["@vellumai/egress-proxy@file:../packages/egress-proxy", { "devDependencies": { "@types/bun": "1.3.10", "typescript": "5.9.3" } }],
 
+    "@vellumai/environments": ["@vellumai/environments@file:../packages/environments", { "devDependencies": { "@types/bun": "1.3.11", "typescript": "5.9.3" } }],
+
     "@vellumai/gateway-client": ["@vellumai/gateway-client@file:../packages/gateway-client", { "dependencies": { "@vellumai/service-contracts": "file:../service-contracts" }, "devDependencies": { "@types/bun": "1.3.10", "typescript": "5.9.3" } }],
 
     "@vellumai/ipc-server-utils": ["@vellumai/ipc-server-utils@file:../packages/ipc-server-utils", { "devDependencies": { "@types/bun": "1.3.10", "typescript": "5.9.3" } }],
@@ -1260,6 +1265,8 @@
 
     "@vellumai/ces-client/typescript": ["typescript@5.7.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-84MVSjMEHP+FQRPy3pX9sTVV/INIex71s9TL2Gm5FG/WG1SqXeKyZ0k7/blY/4FdOzI12CBy1vGc4og/eus0fw=="],
 
+    "@vellumai/environments/@types/bun": ["@types/bun@1.3.11", "", { "dependencies": { "bun-types": "1.3.11" } }, "sha512-5vPne5QvtpjGpsGYXiFyycfpDF2ECyPcTSsFBMa0fraoxiQyMJ3SmuQIGhzPg2WJuWxVBoxWJ2kClYTcw/4fAg=="],
+
     "@vellumai/gateway-client/@vellumai/service-contracts": ["@vellumai/service-contracts@file:../packages/service-contracts", { "dependencies": { "zod": "4.3.6" }, "devDependencies": { "@types/bun": "1.2.4", "typescript": "5.7.3" } }],
 
     "ajv-formats/ajv": ["ajv@8.20.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA=="],
@@ -1376,6 +1383,8 @@
 
     "@vellumai/ces-client/@vellumai/service-contracts/typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
+    "@vellumai/environments/@types/bun/bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
+
     "ajv-formats/ajv/json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
 
     "cross-spawn/which/isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],

package/docker-entrypoint.sh

@@ -6,9 +6,11 @@ set -eu
 chmod 1777 /tmp 2>/dev/null || true
 
 KATA_APT_INIT_PID=""
-if [ "${VELLUM_SANDBOX_RUNTIME:-}" = "kata" ] && [ -x /app/assistant/docker-init-apt-root.sh ]; then
+. /app/assistant/docker-kata-runtime-family.sh
+
+if vellum_is_kata_family_runtime && [ -x /app/assistant/docker-init-apt-root.sh ]; then
   export VELLUM_APT_DATA_ROOT="${VELLUM_APT_DATA_ROOT:-/data/system}"
-  # Warm the chroot used by kata apt wrappers without blocking assistant readiness.
+  # Warm the chroot used by Kata-family apt wrappers without blocking assistant readiness.
   /app/assistant/docker-init-apt-root.sh &
   KATA_APT_INIT_PID="$!"
 fi
@@ -25,15 +27,17 @@ if [ "$(id -u)" = "0" ] && [ "${VELLUM_WORKSPACE_DIR:-}" = "/workspace" ] && [ -
   git config --global --add safe.directory '/workspace/*' >/dev/null 2>&1 || true
 fi
 
-# Source executable scripts from /workspace/.entrypoint.d/ in lexicographic
-# order so an assistant can extend the daemon environment from its own
-# workspace volume — PATH additions, credential helpers, tooling symlinks.
-# Scripts are sourced so env mutations propagate to the daemon. Errors are
-# logged but non-fatal.
+# Source workspace entrypoint hooks from /workspace/.entrypoint.d/ in
+# lexicographic order. Hooks must be regular files (symlinks are rejected)
+# and have the executable bit set. Scripts are sourced so env mutations
+# propagate to the daemon. Errors are logged but non-fatal.
 if [ -d /workspace/.entrypoint.d ]; then
   for hook in /workspace/.entrypoint.d/*.sh; do
-    [ -r "$hook" ] || continue
+    [ ! -L "$hook" ] || continue
+    [ -x "$hook" ] || continue
     wait_for_kata_apt_root
+    [ ! -L "$hook" ] || continue
+    [ -x "$hook" ] || continue
     . "$hook" || echo "Warning: workspace hook $hook exited $?" >&2
   done
 fi

package/docker-init-apt-root.sh

@@ -10,7 +10,9 @@ LOCK_DIR="${DATA_ROOT}.rootfs-init.lock"
 LOCK_PID="${LOCK_DIR}/pid"
 HOST_PATH="/usr/sbin:/usr/bin:/sbin:/bin"
 
-if [ "${VELLUM_SANDBOX_RUNTIME:-}" != "kata" ]; then
+. /app/assistant/docker-kata-runtime-family.sh
+
+if ! vellum_is_kata_family_runtime; then
   exit 0
 fi
 

package/docker-kata-apt-env.sh

@@ -1,6 +1,8 @@
 #!/usr/bin/env sh
 
-if [ "${VELLUM_SANDBOX_RUNTIME:-}" != "kata" ]; then
+. /app/assistant/docker-kata-runtime-family.sh
+
+if ! vellum_is_kata_family_runtime; then
   return 0 2>/dev/null || exit 0
 fi
 

package/docker-kata-runtime-family.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env sh
+
+vellum_is_kata_family_runtime() {
+  case "${VELLUM_SANDBOX_RUNTIME:-}" in
+    kata|firecracker|cloud-hypervisor)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}

package/docs/architecture/memory.md

@@ -244,7 +244,7 @@ graph TB
 
 Normal context compaction (the "Context Window Management" subgraph above) runs proactively as the conversation approaches the token limit, using cooldown guards and a severity-pressure override to balance compaction frequency against cost. This is the primary defense against context overflow.
 
-When compaction alone is insufficient — either because the conversation grew too fast between turns or because a single turn contains extremely large payloads — the overflow recovery pipeline takes over. The pipeline's first tier (forced compaction) reuses the same `maybeCompact()` summarization machinery but with emergency parameters: `force: true` bypasses cooldown guards, `minKeepRecentUserTurns: 0` allows summarizing even the most recent history, and `targetInputTokensOverride` sets a tighter budget. Subsequent tiers (tool-result truncation, media stubbing, injection downgrade) apply progressively more aggressive payload reduction without involving the summarizer.
+When compaction alone is insufficient — either because the conversation grew too fast between turns or because a single turn contains extremely large payloads — the overflow recovery pipeline takes over. The pipeline's first tier (forced compaction) reuses the same `maybeCompact()` summarization machinery but with emergency parameters: `force: true` bypasses cooldown guards and `minKeepRecentUserTurns: 0` allows summarizing even the most recent history. The reducer drives convergence toward a tighter budget by re-invoking each tier until the estimated tokens fall under its `targetTokens` ceiling. Subsequent tiers (tool-result truncation, media stubbing, injection downgrade) apply progressively more aggressive payload reduction without involving the summarizer.
 
 If all four reducer tiers are exhausted, the overflow policy resolver determines whether to compress the latest user turn. All sessions — interactive and non-interactive alike — auto-compress the latest turn without prompting. The only explicit opt-out is setting `contextWindow.overflowRecovery.interactiveLatestTurnCompression` (or `nonInteractiveLatestTurnCompression`) to `"drop"`, which short-circuits to a graceful failure instead. Disabling overflow recovery entirely (`contextWindow.overflowRecovery.enabled: false`) also yields a graceful failure.
 

package/docs/plugins.md

@@ -1,23 +1,33 @@
-# 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` + 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)
+- [Hooks](#hooks)
 - [Pipeline reference](#pipeline-reference)
 - [Timeouts](#timeouts)
 - [Strict-fail semantics](#strict-fail-semantics)
@@ -29,6 +39,32 @@ 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 `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 & per-turn hooks | `plugin.hooks`      | keyed by hook name (`init`, `shutdown`, …)        |
+
+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
@@ -50,9 +86,8 @@ 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[];
@@ -61,8 +96,9 @@ export interface Plugin {
 ```
 
 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
 
@@ -275,7 +311,7 @@ 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:
+Five common patterns emerge from that signature:
 
 ### Observe-only
 
@@ -284,8 +320,8 @@ 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 observer: Middleware<MemoryArgs, MemoryResult> =
+  async function observeRetrieval(args, next, ctx) {
     const start = performance.now();
     let outcome: "success" | "error" = "success";
     try {
@@ -295,27 +331,22 @@ const observer: Middleware<ToolExecuteArgs, ToolExecuteResult> =
       throw err;
     } finally {
       const ms = Math.round(performance.now() - start);
-      console.error(JSON.stringify({ tool: args.name, ms, outcome }));
+      console.error(
+        JSON.stringify({ conversationId: args.conversationId, ms, outcome }),
+      );
     }
   };
 ```
 
 ### Transform input
 
-Rewrite `args` before calling downstream. Useful for request shimming
-(adding headers, redacting inputs, picking a different provider).
+Rewrite `args` before calling downstream. Useful for reshaping the inputs
+(forcing an untrusted read, narrowing the turn the retriever sees).
 
 ```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);
+const untrustedRead: Middleware<MemoryArgs, MemoryResult> =
+  async function untrustedRead(args, next, ctx) {
+    return next({ ...args, trustContext: undefined });
   };
 ```
 
@@ -324,14 +355,14 @@ const addHeader: Middleware<LLMCallArgs, LLMCallResult> =
 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),
-    };
-  };
+const dropNow: Middleware<MemoryArgs, MemoryResult> = async function dropNow(
+  args,
+  next,
+  ctx,
+) {
+  const result = await next(args);
+  return { ...result, nowContent: null };
+};
 ```
 
 ### Short-circuit
@@ -341,10 +372,11 @@ 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;
+const skipUntrusted: Middleware<MemoryArgs, MemoryResult> =
+  async function skipUntrusted(args, next, ctx) {
+    if (!isTrusted(ctx.trust)) {
+      return { pkbContent: null, nowContent: null, graphResult: null };
+    }
     return next(args);
   };
 ```
@@ -356,10 +388,10 @@ 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`);
+const denyIfUntrusted: Middleware<CompactionArgs, CompactionResult> =
+  async function denyIfUntrusted(args, next, ctx) {
+    if (!isTrusted(ctx.trust)) {
+      throw new Error(`compaction denied by policy`);
     }
     return next(args);
   };
@@ -372,30 +404,38 @@ 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
+plugin.pipeline pipeline=compaction chain=["observeCompaction","defaultCompaction"] durationMs=1840 outcome=success
 ```
 
+## Hooks
+
+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).
+
+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.
+
+| 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`             |
+
 ## 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.        |
+| Pipeline     | Purpose                                                                      |
+| ------------ | ---------------------------------------------------------------------------- |
+| `compaction` | The conversation-compaction step. Wraps `ContextWindowManager.maybeCompact`. |
 
 ## Timeouts
 
@@ -406,22 +446,9 @@ 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.                                                                   |
+| Pipeline     | Timeout  | Rationale                                                                                            |
+| ------------ | -------- | ---------------------------------------------------------------------------------------------------- |
+| `compaction` | 30000 ms | Summarization involves a provider call; mirrors the pipeline-level budget for LLM-backed operations. |
 
 `null` timeouts skip the timer entirely. Finite timeouts arm a
 `setTimeout` that races the pipeline via `Promise.race`.
@@ -758,7 +785,7 @@ Every pipeline invocation emits one structured line tagged
 
 | Field                                      | Meaning                                                                 |
 | ------------------------------------------ | ----------------------------------------------------------------------- |
-| `pipeline`                                 | Pipeline name (`llmCall`, `toolExecute`, …).                            |
+| `pipeline`                                 | Pipeline name (`compaction`).                                           |
 | `chain`                                    | Ordered list of middleware function names, outermost first.             |
 | `durationMs`                               | Total time spent in the composed chain.                                 |
 | `outcome`                                  | `"success"`, `"error"`, or `"timeout"`.                                 |

package/examples/plugins/echo/README.md

@@ -4,8 +4,12 @@ Minimal example plugin. Observes every assistant pipeline and logs one JSON
 line per invocation to `stderr`:
 
 ```json
-{"plugin":"echo","pipeline":"toolExecute","durationMs":42,"outcome":"success"}
-{"plugin":"echo","pipeline":"llmCall","durationMs":1873,"outcome":"success"}
+{
+  "plugin": "echo",
+  "pipeline": "compaction",
+  "durationMs": 1590,
+  "outcome": "success"
+}
 ```
 
 Use this as a starting point for writing your own plugin, or as a quick way
@@ -18,10 +22,7 @@ For the full plugin authoring guide, see
 ## 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`.
+  `PipelineMiddlewareMap` — `compaction`.
 - 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.
@@ -96,12 +97,12 @@ tail -f ~/.vellum/daemon.log
 You should see one line per pipeline 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",
+  "pipeline": "compaction",
+  "durationMs": 1590,
+  "outcome": "success"
+}
 ```
 
 If a pipeline throws (for example, a tool that errors out), you'll see a