@vellumai/assistant 0.8.5 → 0.8.7

package/AGENTS.md

@@ -14,7 +14,9 @@ When you introduce a new env var that the assistant process needs to read at run
 
 ## Daemon startup philosophy
 
-The daemon must **never** block startup under _any circumstance_. All possible errors should be logged so that the assistant can recover from it's corrupted state after the fact.
+The daemon must **never** block startup due to **subsystem** failures (DB, Qdrant, plugins, feature flags, etc.). If an individual subsystem fails, log the error and continue in degraded mode so the process remains reachable for health checks and diagnostics.
+
+**Exception — duplicate daemon detection:** If the daemon cannot establish **any** client-facing transport because another daemon already holds both the IPC socket and HTTP port, it must exit immediately. A daemon with no transport is unmanageable (invisible to health checks, unreachable by stop commands) yet still runs background jobs (scheduler, memory worker, background wake) against the shared database, causing duplicate side effects.
 
 ## Post-execution hooks
 
@@ -39,6 +41,7 @@ Routes in `src/runtime/routes/` are being migrated to a **shared `ROUTES` array*
 The CLI and daemon communicate over a Unix domain socket using **length-prefixed binary framing**: each frame is a 4-byte big-endian length followed by a payload. Messages use a JSON envelope `{ id, method, params?, headers? }` for requests and `{ id, result?, error?, headers? }` for responses.
 
 Three response shapes are supported:
+
 - **JSON-only**: a single JSON frame (no `content-length` or `transfer-encoding` header).
 - **Binary**: a JSON envelope with `headers: { "content-length": "<n>" }` followed by one binary frame of exactly `n` bytes.
 - **Chunked streaming**: a JSON envelope with `headers: { "transfer-encoding": "chunked" }` followed by one or more binary frames, terminated by a zero-length frame.
@@ -55,6 +58,35 @@ Some routes are IPC-only (defined in `src/ipc/routes/`, not in the shared array)
 
 The module-level dependency-injection pattern (`registerFooDeps()`) used by some IPC routes is a known antipattern. New IPC-only routes should avoid it.
 
+## SQLite WAL checkpointing
+
+**Never run `PRAGMA wal_checkpoint(TRUNCATE)` from a subprocess** (i.e. from `runAsyncSqlite` or any other path that opens a fresh SQLite connection while the daemon's in-process connection is live).
+
+TRUNCATE has a side effect documented in the SQLite source but not in most surface-level docs: after writing all committed WAL pages to the main database file, if the resulting WAL file is empty, SQLite **unlinks the `.wal` (and `.shm`) file from the directory**. This is fine when the connection running the checkpoint is the only connection — the next opener creates a fresh WAL. It is **not** fine when a peer connection (the daemon) still holds open file descriptors to the original WAL inode: the unlink orphans those fds into a "ghost WAL" only the daemon can reach, every subsequent connection creates a new `.wal`/`.shm` pair on disk, and you get split-brain — daemon and outside readers see different data, no errors logged on either side. The symptom in `/proc/<daemon-pid>/fd/` is the unmistakable `(deleted)` suffix on the daemon's WAL/SHM entries while the main DB fd looks normal.
+
+Use these instead:
+
+- **`PRAGMA wal_checkpoint(FULL)`** when you need flush-completion (export readers, migration snapshots — anywhere downstream reads the main `.db` file). FULL blocks until all committed WAL pages are written to the main DB but does _not_ truncate the WAL file size, so the unlink side effect does not fire.
+- **`PRAGMA wal_checkpoint(PASSIVE)`** for background/amortized housekeeping where partial progress is acceptable. PASSIVE makes no attempt to acquire locks that would conflict with active readers, so it never reaches the empty-WAL state in a contested environment.
+- **Autocheckpoint** (`PRAGMA wal_autocheckpoint = <pages>`, default 1000) handles the routine "keep the WAL bounded" case without any explicit PRAGMA call.
+
+TRUNCATE _is_ safe on the daemon's own long-lived in-process connection (e.g. at startup or during shutdown when no peer connections exist). Today `src/memory/db-init.ts` and `src/daemon/shutdown-handlers.ts` legitimately use it. **Do not copy that pattern into any code path that runs via `runAsyncSqlite` or otherwise spawns a separate process.**
+
 ## Code comments
 
 When writing or updating comments, **do not reference code that has been removed.** Comments should describe the current state of the codebase, not narrate its history. Avoid phrases like "no longer does X", "previously used Y", or "was removed in PR Z" — future readers should not need to understand past implementations to understand the current code.
+
+## Test machinery isolation
+
+**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 _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 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 (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/ARCHITECTURE.md

@@ -23,7 +23,7 @@ This document owns assistant-runtime architecture details. The repo-level archit
 
 ### Safe Storage Limits
 
-Safe storage limits are gated by the assistant feature flag `safe-storage-limits`, default off. When the flag is off, the disk pressure guard reports a disabled status and no runtime path blocks work, injects cleanup guidance, or changes tool access.
+Safe storage limits protect the workspace volume from running out of disk. The disk pressure guard samples storage continuously and blocks work, injects cleanup guidance, and narrows tool access while the workspace is critically full.
 
 **Disk pressure state:** `src/daemon/disk-pressure-guard.ts` samples workspace storage usage every 60 seconds through `src/util/disk-usage.ts`. At or above the 95% critical threshold it creates an in-memory lock with `lockId`, usage snapshot, `acknowledged`, `overrideActive`, `effectivelyLocked`, and the blocked capabilities `agent-turns`, `background-work`, and `remote-ingress`. The lock clears when usage drops below the threshold or the process restarts. `acknowledgeDiskPressureLock()` only lets the guardian enter cleanup mode; `overrideDiskPressureLock()` requires the exact phrase `I understand the risks` and disables the effective lock while usage remains critical.
 

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

package/bun.lock

@@ -11,12 +11,11 @@
         "@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": {
@@ -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/bunfig.toml

@@ -3,4 +3,9 @@ exact = true
 
 [test]
 root = "./src"
-preload = ["./src/__tests__/test-preload.ts"]
+# Order matters: the verifier reads state set by the main preload, so it
+# MUST be listed second. See test-preload-verifier.ts for context.
+preload = [
+  "./src/__tests__/test-preload.ts",
+  "./src/__tests__/test-preload-verifier.ts",
+]

package/docker-entrypoint.sh

@@ -25,15 +25,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/docs/credential-execution-service.md

@@ -172,11 +172,11 @@ Audit logs record every materialization event with: grant ID, credential ID, too
 
 CES and the assistant share contract definitions and credential-storage abstractions through three private packages in `packages/`:
 
-| Package                          | Purpose                                                                                                                                                                                                                    | Consumers                            |
-| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
-| `@vellumai/service-contracts`    | RPC protocol types, method names, protocol version constant, grant shapes, credential handle types, and rendering helpers. Consumed via explicit domain subpaths (e.g. `@vellumai/service-contracts/credential-rpc`). | `assistant/`, `credential-executor/` |
-| `@vellumai/credential-storage`   | Credential store read API (static secrets and OAuth runtime), unified credential handle abstraction                                                                                                                         | `assistant/`, `credential-executor/` |
-| `@vellumai/egress-proxy`         | Session-scoped egress proxy lifecycle (create, start, stop, env-var injection)                                                                                                                                             | `assistant/`, `credential-executor/` |
+| Package                        | Purpose                                                                                                                                                                                                               | Consumers                            |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| `@vellumai/service-contracts`  | RPC protocol types, method names, protocol version constant, grant shapes, credential handle types, and rendering helpers. Consumed via explicit domain subpaths (e.g. `@vellumai/service-contracts/credential-rpc`). | `assistant/`, `credential-executor/` |
+| `@vellumai/credential-storage` | Credential store read API (static secrets and OAuth runtime), unified credential handle abstraction                                                                                                                   | `assistant/`, `credential-executor/` |
+| `@vellumai/egress-proxy`       | Session-scoped egress proxy lifecycle (create, start, stop, env-var injection)                                                                                                                                        | `assistant/`, `credential-executor/` |
 
 These packages are the **only** allowed shared-code path between the assistant and CES. Direct source imports between `assistant/` and `credential-executor/` remain banned. The packages are built locally via `workspace:*` references and copied into the CES Docker image at build time (`COPY packages/ ...` in `credential-executor/Dockerfile`).
 
@@ -229,7 +229,7 @@ These invariants are enforced by guard tests and code review:
 4. **Grants and audit logs are CES-internal**: The assistant cannot read CES grant tables or audit logs directly. CES exposes grant status and audit summaries via RPC responses.
 5. **No generic authenticated HTTP clients in secure commands**: `curl`, `wget`, `httpie`, interpreters, and shell trampolines are structurally denied as secure command entrypoints. This is checked at manifest validation and re-checked at execution time.
 6. **Managed CES container runs as non-root**: The CES Docker image runs as `uid 1001` (user `ces`). The CES data volume is owned by this user.
-7. **Single-connection bootstrap socket**: In managed mode, CES accepts exactly one connection on the bootstrap socket, then unlinks it. No second process can connect.
+7. **Single active bootstrap connection**: In managed mode, CES accepts one connection on the bootstrap socket and unlinks the socket path while that connection is live, so no second process can connect concurrently. CES is a long-lived sidecar: when the active session ends (the assistant disconnects or its container restarts), CES re-binds the socket and awaits the assistant's reconnection rather than shutting down. At most one connection is ever active; the sidecar only exits on SIGTERM/SIGINT.
 
 ## Rollout
 

package/docs/plugins.md

@@ -1,18 +1,27 @@
-# 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)
@@ -29,6 +38,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               | `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
@@ -380,22 +415,22 @@ plugin.pipeline pipeline=llmCall chain=["observeLlm","addHeader","defaultLlmCall
 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                                                                                                                                            |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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
 
@@ -548,9 +583,10 @@ middleware. Each is optional.
 
 An array of `Tool` objects. The bootstrap registers them with the global
 tool registry after `init()` succeeds, stamping `origin: "plugin"` and
-`ownerPluginId: <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).
+`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 = {

package/examples/plugins/echo/register.ts

@@ -40,6 +40,10 @@
  * user-plugin-loader contract (see `assistant/src/plugins/user-loader.ts`).
  */
 
+import type {
+  ToolResultTruncateArgs,
+  ToolResultTruncateResult,
+} from "../../../src/plugins/defaults/tool-result-truncate/types.js";
 import type { VellumPluginRuntime } from "../../../src/plugins/external-api.js";
 import type {
   CircuitBreakerArgs,
@@ -48,8 +52,6 @@ import type {
   CompactionResult,
   EmptyResponseArgs,
   EmptyResponseResult,
-  HistoryRepairArgs,
-  HistoryRepairResult,
   LLMCallArgs,
   LLMCallResult,
   MemoryArgs,
@@ -67,8 +69,6 @@ import type {
   ToolErrorResult,
   ToolExecuteArgs,
   ToolExecuteResult,
-  ToolResultTruncateArgs,
-  ToolResultTruncateResult,
   TurnArgs,
   TurnResult,
 } from "../../../src/plugins/types.js";
@@ -156,9 +156,6 @@ const echoPlugin: Plugin = {
       "toolExecute",
     ),
     memoryRetrieval: makeObserver<MemoryArgs, MemoryResult>("memoryRetrieval"),
-    historyRepair: makeObserver<HistoryRepairArgs, HistoryRepairResult>(
-      "historyRepair",
-    ),
     tokenEstimate: makeObserver<TokenEstimateArgs, TokenEstimateResult>(
       "tokenEstimate",
     ),

package/knip.json

@@ -12,6 +12,7 @@
     "@vellumai/ces-client",
     "@vellumai/credential-storage",
     "@vellumai/egress-proxy",
+    "@vellumai/environments",
     "@vellumai/gateway-client",
     "@vellumai/ipc-server-utils",
     "@vellumai/service-contracts",

package/node_modules/@vellumai/environments/bun.lock

@@ -0,0 +1,24 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@vellumai/environments",
+      "devDependencies": {
+        "@types/bun": "1.3.11",
+        "typescript": "5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.11", "", { "dependencies": { "bun-types": "1.3.11" } }, "sha512-5vPne5QvtpjGpsGYXiFyycfpDF2ECyPcTSsFBMa0fraoxiQyMJ3SmuQIGhzPg2WJuWxVBoxWJ2kClYTcw/4fAg=="],
+
+    "@types/node": ["@types/node@25.9.1", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-xfrlY7UD5rMJk3ZVJP8BNzS28J36YJg+xp+LPXV1TdWxr8uMH5A860QNxYDGQe/ylDSgjxE52Q9VnO7p75tJxg=="],
+
+    "bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
+  }
+}

package/node_modules/@vellumai/environments/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@vellumai/environments",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.11",
+    "typescript": "5.9.3"
+  }
+}

package/node_modules/@vellumai/environments/src/__tests__/package-boundary.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Package boundary tests for @vellumai/environments.
+ *
+ * This package is the lowest layer of the shared-packages hierarchy: pure
+ * environment types and constants with no runtime dependencies. It must
+ * stay a leaf so any consumer (CLI, assistant, local-mode host) can depend
+ * on it without dragging in a dependency tree.
+ *
+ * Enforces that the package:
+ * 1. Imports only node builtins and its own relative modules — no `@vellumai/*`
+ *    packages and no third-party runtime imports.
+ * 2. Declares no runtime `dependencies` (devDependencies only).
+ * 3. Is marked `private`.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const PACKAGE_ROOT = resolve(import.meta.dirname, "../..");
+const SRC_DIR = join(PACKAGE_ROOT, "src");
+
+function collectSourceFiles(dir: string): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      if (entry === "node_modules" || entry === "__tests__") continue;
+      files.push(...collectSourceFiles(full));
+    } else if (
+      entry.endsWith(".ts") &&
+      !entry.endsWith(".test.ts") &&
+      !entry.endsWith(".d.ts")
+    ) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/**
+ * Matches the module specifier of any `import ... from "<spec>"` /
+ * `export ... from "<spec>"` / `require("<spec>")` statement.
+ */
+const IMPORT_SPEC = /(?:from|require\s*\(\s*)["']([^"']+)["']/g;
+
+/** A bare specifier is anything that is not a relative or node-builtin import. */
+function isForbiddenSpecifier(spec: string): boolean {
+  if (spec.startsWith(".") || spec.startsWith("/")) return false;
+  if (spec.startsWith("node:")) return false;
+  return true;
+}
+
+describe("package boundary", () => {
+  const sourceFiles = collectSourceFiles(SRC_DIR);
+
+  test("has source files to validate", () => {
+    expect(sourceFiles.length).toBeGreaterThan(0);
+  });
+
+  test("imports only node builtins and relative modules", () => {
+    const violations: string[] = [];
+
+    for (const file of sourceFiles) {
+      const lines = readFileSync(file, "utf-8").split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        for (const match of lines[i]!.matchAll(IMPORT_SPEC)) {
+          const spec = match[1]!;
+          if (isForbiddenSpecifier(spec)) {
+            const relative = file.replace(PACKAGE_ROOT + "/", "");
+            violations.push(`${relative}:${i + 1}: ${spec}`);
+          }
+        }
+      }
+    }
+
+    if (violations.length > 0) {
+      throw new Error(
+        `Found ${violations.length} forbidden import(s) in @vellumai/environments:\n` +
+          violations.map((v) => `  - ${v}`).join("\n") +
+          "\n\n@vellumai/environments is a pure types/constants leaf and must\n" +
+          "import only node builtins and its own relative modules.",
+      );
+    }
+  });
+
+  test("package.json declares it as private with no runtime dependencies", () => {
+    const pkg = JSON.parse(
+      readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8"),
+    );
+    expect(pkg.private).toBe(true);
+    expect(pkg.dependencies ?? {}).toEqual({});
+  });
+});

package/node_modules/@vellumai/environments/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @vellumai/environments — the single source of truth for Vellum's known
+ * deployment environments (names, platform/web URLs, per-service port
+ * blocks). Consumed by the CLI, the assistant daemon, and the local-mode
+ * host library so the environment list is defined exactly once on the TS
+ * side. The Swift client mirrors the same set in `VellumEnvironment.swift`.
+ *
+ * Intentionally free of runtime dependencies: pure types and constants only.
+ */
+export * from "./types.js";
+export * from "./seeds.js";

package/node_modules/@vellumai/environments/src/seeds.ts

@@ -0,0 +1,73 @@
+import type { EnvironmentDefinition, PortMap } from "./types.js";
+
+/**
+ * Non-prod port blocks. Each environment gets a 1000-port window in the
+ * 17000–21000 band. Within a block, services are spaced 100 apart so up to
+ * 100 assistants can coexist without the scan (`findAvailablePort`) running
+ * one service's range into the next. Band chosen to sit below Linux's
+ * default ephemeral start (32768) and macOS's (49152), and away from the
+ * 3000/5000/8000/9000 dev-tool swamp. Production keeps its legacy,
+ * non-contiguous port set (7821/7830/6333/8090/8080/8765): cross-env
+ * collision is the only problem this change targets, prod is unaffected
+ * because only one env's assistants compete on a given machine, and
+ * churning it would leave existing hatches on 7821 while new ones
+ * allocated elsewhere.
+ */
+function portBlock(base: number): PortMap {
+  return {
+    daemon: base,
+    gateway: base + 100,
+    qdrant: base + 200,
+    ces: base + 300,
+    outboundProxy: base + 400,
+    tcp: base + 500,
+  };
+}
+
+/**
+ * Built-in environment definitions and the TS-side source of truth for the
+ * set of known environment names. The Swift client mirrors this list in
+ * `clients/macos/vellum-assistant/App/VellumEnvironment.swift`; since Swift
+ * can't import TypeScript, drift between the two is caught at test time by
+ * `cli/src/__tests__/env-drift.test.ts`.
+ *
+ * Custom environments via a user config file are a future phase — see the
+ * "Coexisting environments" design doc. Until then, a call site that needs a
+ * new environment must add it here and rebuild.
+ */
+export const SEEDS: Record<string, EnvironmentDefinition> = {
+  production: {
+    name: "production",
+    platformUrl: "https://platform.vellum.ai",
+    webUrl: "https://www.vellum.ai",
+  },
+  staging: {
+    name: "staging",
+    platformUrl: "https://staging-platform.vellum.ai",
+    webUrl: "https://staging-assistant.vellum.ai",
+    portsOverride: portBlock(17000),
+  },
+  test: {
+    name: "test",
+    // Non-functional URL — used only by unit tests for URL resolution, never
+    // hit in production.
+    platformUrl: "https://test-platform.vellum.ai",
+    webUrl: "https://dev-assistant.vellum.ai",
+    portsOverride: portBlock(19000),
+  },
+  dev: {
+    name: "dev",
+    platformUrl: "https://dev-platform.vellum.ai",
+    webUrl: "https://dev-assistant.vellum.ai",
+    portsOverride: portBlock(18000),
+  },
+  local: {
+    name: "local",
+    platformUrl: "http://localhost:8000",
+    webUrl: "http://localhost:3000",
+    // assistantPlatformUrl: "http://host.docker.internal:8000",
+    // ^ uncomment this once dockerized hatch path is live.
+    // The assistant runs in a different network namespace than the host.
+    portsOverride: portBlock(20000),
+  },
+};