@vellumai/assistant 0.8.6 → 0.8.7

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

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/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/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
 

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),
+  },
+};

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

@@ -0,0 +1,70 @@
+/**
+ * Environment type definitions. Environments are deployment targets with
+ * their own platform backend and their own isolated on-host state. See the
+ * "Coexisting environments" design doc for the full model.
+ */
+
+/**
+ * Per-service default port set. Phase 5 (per-environment port offsets) is
+ * deferred from MVP, so today every environment uses the same port set. The
+ * shape exists so the rest of the stack can call `getDefaultPorts(env)` and
+ * gain per-env offsets later without changing any call sites.
+ */
+export interface PortMap {
+  daemon: number;
+  gateway: number;
+  qdrant: number;
+  ces: number;
+  outboundProxy: number;
+  tcp: number;
+}
+
+/**
+ * A resolved environment definition. Required fields are `name` and
+ * `platformUrl`. All other fields are optional and declared upfront — new
+ * fields are additive, never breaking. `name` is intentionally typed as
+ * `string` (not `keyof SEEDS`) so custom environments can be represented by
+ * future layers (user config file, ad-hoc env vars, etc.).
+ */
+export interface EnvironmentDefinition {
+  name: string;
+  platformUrl: string;
+
+  /**
+   * The web app (Next.js) base URL for browser-facing pages like
+   * `/account/login`. In production this is separate from the API backend
+   * (e.g. `www.vellum.ai` vs `platform.vellum.ai`); locally it's
+   * `localhost:3000` vs `localhost:8000`.
+   *
+   * Mirrors `VellumEnvironment.webURL` on the Swift side.
+   */
+  webUrl: string;
+
+  /**
+   * Override for the platform URL the assistant process itself uses. Only
+   * differs from `platformUrl` when the assistant runs in a different network
+   * namespace than the host (e.g. Docker on macOS, where the host's localhost
+   * is reached via `host.docker.internal`). Falls back to `platformUrl` when
+   * unset.
+   */
+  assistantPlatformUrl?: string;
+
+  /** Human-readable label for UI surfaces. */
+  displayName?: string;
+
+  /** Hint for UI surfaces that want to tint or badge their display. */
+  tintColor?: string;
+
+  /** Per-service port overrides merged on top of defaults. */
+  portsOverride?: Partial<PortMap>;
+
+  /** Override for the XDG config directory. */
+  configDirOverride?: string;
+
+  /**
+   * Override for the directory containing the lockfile. Populated by the
+   * resolver from `VELLUM_LOCKFILE_DIR` (an existing e2e test escape hatch)
+   * so path helpers don't read env vars directly.
+   */
+  lockfileDirOverride?: string;
+}

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

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

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

@@ -30,6 +30,13 @@ export interface AssistantEvent<TMessage = unknown> {
   id: string;
   /** Resolved conversation id when available. */
   conversationId?: string;
+  /**
+   * Monotonic per-conversation sequence number. Assigned by the daemon at
+   * publish time for conversation-scoped events; absent for unscoped
+   * broadcasts. Clients track the highest observed `seq` per conversation
+   * and pass it back on reconnect to request replay of missed events.
+   */
+  seq?: number;
   /** ISO-8601 timestamp of when the event was emitted. */
   emittedAt: string;
   /** Outbound message payload. */
@@ -70,6 +77,10 @@ export function buildAssistantEvent<TMessage>(
  * data: <JSON>\n
  * \n
  * ```
+ *
+ * The SSE `id:` line is the per-event UUID and is intentionally decoupled
+ * from any replay cursor. Replay-aware consumers read `seq` from the JSON
+ * payload of the envelope itself.
  */
 export function formatSseFrame(event: AssistantEvent): string {
   const sanitizedId = event.id.replace(/[\n\r]/g, "");

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

@@ -969,15 +969,14 @@ export class SkillHostClient implements SkillHost {
       conversationId,
       role,
       content,
-      metadata,
-      opts,
+      options,
     ) =>
       this.call("host.memory.addMessage", {
         conversationId,
         role,
         content,
-        metadata,
-        opts,
+        metadata: options?.metadata,
+        skipIndexing: options?.skipIndexing,
       });
 
     return {