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

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`.
@@ -548,9 +575,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 = {
@@ -757,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

package/examples/plugins/echo/register.ts

@@ -42,35 +42,9 @@
 
 import type { VellumPluginRuntime } from "../../../src/plugins/external-api.js";
 import type {
-  CircuitBreakerArgs,
-  CircuitBreakerResult,
   CompactionArgs,
   CompactionResult,
-  EmptyResponseArgs,
-  EmptyResponseResult,
-  HistoryRepairArgs,
-  HistoryRepairResult,
-  LLMCallArgs,
-  LLMCallResult,
-  MemoryArgs,
-  MemoryResult,
-  OverflowReduceArgs,
-  OverflowReduceResult,
-  PersistArgs,
-  PersistResult,
   Plugin,
-  TitleArgs,
-  TitleResult,
-  TokenEstimateArgs,
-  TokenEstimateResult,
-  ToolErrorArgs,
-  ToolErrorResult,
-  ToolExecuteArgs,
-  ToolExecuteResult,
-  ToolResultTruncateArgs,
-  ToolResultTruncateResult,
-  TurnArgs,
-  TurnResult,
 } from "../../../src/plugins/types.js";
 
 const runtime = (globalThis as { __vellumPluginRuntime?: VellumPluginRuntime })
@@ -150,35 +124,7 @@ const echoPlugin: Plugin = {
     version: "0.1.0",
   },
   middleware: {
-    turn: makeObserver<TurnArgs, TurnResult>("turn"),
-    llmCall: makeObserver<LLMCallArgs, LLMCallResult>("llmCall"),
-    toolExecute: makeObserver<ToolExecuteArgs, ToolExecuteResult>(
-      "toolExecute",
-    ),
-    memoryRetrieval: makeObserver<MemoryArgs, MemoryResult>("memoryRetrieval"),
-    historyRepair: makeObserver<HistoryRepairArgs, HistoryRepairResult>(
-      "historyRepair",
-    ),
-    tokenEstimate: makeObserver<TokenEstimateArgs, TokenEstimateResult>(
-      "tokenEstimate",
-    ),
     compaction: makeObserver<CompactionArgs, CompactionResult>("compaction"),
-    overflowReduce: makeObserver<OverflowReduceArgs, OverflowReduceResult>(
-      "overflowReduce",
-    ),
-    persistence: makeObserver<PersistArgs, PersistResult>("persistence"),
-    titleGenerate: makeObserver<TitleArgs, TitleResult>("titleGenerate"),
-    toolResultTruncate: makeObserver<
-      ToolResultTruncateArgs,
-      ToolResultTruncateResult
-    >("toolResultTruncate"),
-    emptyResponse: makeObserver<EmptyResponseArgs, EmptyResponseResult>(
-      "emptyResponse",
-    ),
-    toolError: makeObserver<ToolErrorArgs, ToolErrorResult>("toolError"),
-    circuitBreaker: makeObserver<CircuitBreakerArgs, CircuitBreakerResult>(
-      "circuitBreaker",
-    ),
   },
 };
 

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";