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

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

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 {

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

@@ -16,9 +16,9 @@
  * Moving the fully typed discriminated union into this package would
  * require relocating `assistant/src/daemon/message-types/` and its
  * cross-file type dependencies (`channels/types.ts`,
- * `skills/skillssh-registry.ts`, `runtime/guardian-decision-types.ts`,
- * `gallery/gallery-manifest.ts`). That is out of scope for PR 3 of the
- * skill-isolation plan and is tracked for later iteration.
+ * `skills/skillssh-registry.ts`, `runtime/guardian-decision-types.ts`).
+ * That is out of scope for PR 3 of the skill-isolation plan and is
+ * tracked for later iteration.
  */
 
 /**

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

@@ -194,8 +194,12 @@ export interface ProvidersFacet {
 // Memory
 // ---------------------------------------------------------------------------
 
-/** Valid message roles for `memory.addMessage`. */
-export type MessageRole = "user" | "assistant" | "system";
+/**
+ * Valid message roles for `memory.addMessage`. The messages store is
+ * UI-facing (`ConversationMessage`), so only renderable turns are accepted —
+ * agent-context `system` rows are not persisted via this facet.
+ */
+export type MessageRole = "user" | "assistant";
 
 /**
  * Callable signature for `memory.addMessage`. Mirrors the daemon's
@@ -203,12 +207,16 @@ export type MessageRole = "user" | "assistant" | "system";
  * The return type is left as `unknown` because the daemon has additional
  * fields (message id, metadata echo) that skills should not depend on.
  */
+export interface InsertMessageOptions {
+  metadata?: Record<string, unknown>;
+  skipIndexing?: boolean;
+}
+
 export type InsertMessageFn = (
   conversationId: string,
   role: MessageRole,
   content: string,
-  metadata?: Record<string, unknown>,
-  opts?: { skipIndexing?: boolean },
+  options?: InsertMessageOptions,
 ) => Promise<unknown>;
 
 /** Opaque payload passed to `memory.wakeAgentForOpportunity`. */
@@ -243,10 +251,7 @@ export interface Subscription {
 export interface EventsFacet {
   publish(event: AssistantEvent): Promise<void>;
   subscribe(filter: Filter, cb: AssistantEventCallback): Subscription;
-  buildEvent(
-    message: ServerMessage,
-    conversationId?: string,
-  ): AssistantEvent;
+  buildEvent(message: ServerMessage, conversationId?: string): AssistantEvent;
 }
 
 // ---------------------------------------------------------------------------