@vellumai/vellum-gateway 0.11.7 → 0.11.8-staging.1

package/AGENTS.md

@@ -217,7 +217,7 @@ Two orthogonal axes, do not conflate them:
 - **Admission** (above) — _who gets in the door_. `TRUST_CLASS_RANK` vs `ADMISSION_FLOOR`, enforced across gateway + runtime.
 - **Capabilities** — _what an actor may do once admitted_. Resolved in the runtime, never on the gateway.
 
-**Trust classes** (`TrustClass` in `assistant/src/runtime/actor-trust-resolver.ts`) are the _role_, ranked by `TRUST_CLASS_RANK`:
+**Trust classes** (`TrustClass` in `assistant/src/runtime/trust-class.ts`, re-exported from `actor-trust-resolver.ts`) are the _role_, ranked by `TRUST_CLASS_RANK`:
 
 | Class                | Rank | Meaning                                                                  |
 | -------------------- | ---- | ------------------------------------------------------------------------ |
@@ -262,5 +262,5 @@ The gateway owns guardian approval requests and their delivery records: the `gua
 
 - **Decide atomicity (the core invariant).** `guardian_requests_decide` commits the status CAS (`pending → approved|denied`, first-writer-wins) and the decision's ACL outcome (`activate_member`, `seed_unverified`, `block`, `mint_outbound_session`) in ONE gateway transaction. A failed outcome rolls back the CAS — the request stays `pending` and the guardian can decide again; an `approved` request without its ACL write cannot exist, and deciding twice never applies two outcomes. There is no reopen path.
 - **Schema notes.** There is no `source_type` column — the wire DTO's `sourceType` is derived from `source_channel` (`phone` → voice, `vellum` → desktop, else channel), and the list route translates a `sourceType` filter into `source_channel` predicates. The requester-side conversation is `source_conversation_id`. Request ids are caller-supplied and load-bearing (deterministic access-request ids; `tool_approval` rows reuse the pending-interaction id as PK).
-- **Expiry is daemon-keyed for interaction-bound kinds.** `tool_approval`/`pending_question` requests die with the daemon's in-memory `pendingInteractions` map, so the daemon calls `guardian_requests_expire_interaction_bound` at boot; the gateway never expires them on its own restart. Persistent kinds (`access_request`, `tool_grant_request`) expire past `expires_at` via the daemon's 60s `guardian_requests_sweep_expired` sweep, which returns the expired rows for daemon-side card withdrawal and requester notices.
+- **Expiry is daemon-keyed for interaction-bound kinds.** `tool_approval`/`pending_question` requests die with the daemon's in-memory `pendingInteractions` map, so the daemon calls `guardian_requests_expire_interaction_bound` at boot; the gateway never expires them on its own restart, and the boot call never touches persistent kinds. Persistent kinds (`access_request`, `tool_grant_request`) expire via the daemon's 60s sweep: `guardian_requests_list_expired_pending` returns a bounded, read-only batch of past-deadline pending rows, the daemon runs each row's card withdrawal and requester notice, and only then confirms with the per-request `guardian_requests_expire` CAS, so a lost response or crash leaves the row listed for the next round instead of stranding its side effects. The decide CAS carries an `expires_at` guard, so a decision arriving past the deadline loses the arbitration atomically.
 - **Provenance.** The tables moved here from the assistant DB: gateway data migration m0015 backfilled them, and m0016 (checkpoint-gated on m0015, with a final catch-up copy) dropped the assistant-side tables.

package/ARCHITECTURE.md

@@ -407,7 +407,7 @@ Runtime detects needs_confirmation
 
 **Guardian-aware routing:** When a guardian binding exists for the channel, the approval flow resolves the sender's actor role (`guardian` vs `non-guardian`). Non-guardian actors have `forcePromptSideEffects` set on the session so all side-effect tools trigger approval prompts regardless of existing allow rules. Approval prompts for non-guardian actions are routed to the guardian's delivery chat (not the requester's chat), and a guardian request (kind `tool_approval`) is recorded in the gateway-owned `guardian_requests` table via `guardian_requests_create`. When the guardian approves or denies, the decision commits through `guardian_requests_decide`, is applied to the underlying run, and the requester's chat is notified of the outcome. Guardian actors follow the standard approval flow. Guardian approval follow-ups also use the conversational engine with role-specific context; `approve_always` is downgraded to `approve_once` for guardian approvals since permanent allow-rules require guardian authority. All guardian state (bindings, challenges, guardian requests) is scoped to the `(assistantId, channel)` pair -- the `assistantId` parameter flows through `handleChannelInbound`, `validateAndConsumeVerification`, `isGuardian`, and `getGuardianBinding`.
 
-**Proactive expiry sweep:** The daemon runs a periodic sweep every 60 seconds (`assistant/src/runtime/routes/guardian-expiry-sweep.ts`) that asks the gateway to CAS-expire pending guardian requests past their `expiresAt` (`guardian_requests_sweep_expired`), then fans out card withdrawals and requester expiry notices from the returned rows. This ensures expired approvals are closed without waiting for follow-up traffic from either party.
+**Proactive expiry sweep:** The daemon runs a periodic sweep every 60 seconds (`assistant/src/runtime/routes/guardian-expiry-sweep.ts`) that reads a bounded batch of past-deadline pending requests (`guardian_requests_list_expired_pending`, read-only), fans out card withdrawals and requester expiry notices per row, and only then confirms each with the per-request `guardian_requests_expire` CAS. The status flip is the receipt that the side effects ran: a lost IPC response or a daemon crash leaves the row pending and listed for the next round. Expired approvals close without waiting for follow-up traffic from either party, and a decision arriving past the deadline loses to expiry atomically (the decide CAS guards on `expires_at`).
 
 **Gateway-origin ingress contract:** The JWT token exchanged during gateway-to-runtime authentication proves gateway origin (via the `aud=vellum-daemon` claim). No separate header is required.
 
@@ -422,7 +422,7 @@ Runtime detects needs_confirmation
 | `assistant/src/runtime/routes/channel-routes.ts`        | Integration point: approval interception, actor role resolution, guardian approval routing, deliver-once guard, fail-closed prompt delivery                             |
 | `assistant/src/runtime/channel-verification-service.ts` | Guardian binding lookups: `isGuardian()`, `getGuardianBinding()`                                                                                                        |
 | `assistant/src/memory/delivery-channels.ts`             | `claimRunDelivery()` — in-memory deliver-once guard for terminal reply idempotency                                                                                      |
-| `assistant/src/channels/gateway-guardian-requests.ts`   | Typed daemon client for the gateway-owned `guardian_requests` lifecycle (`guardian_requests_create` / `_decide` / `_sweep_expired`)                                     |
+| `assistant/src/channels/gateway-guardian-requests.ts`   | Typed daemon client for the gateway-owned `guardian_requests` lifecycle (`guardian_requests_create` / `_decide` / `_list_expired_pending` / `_expire`)                  |
 | `assistant/src/runtime/gateway-client.ts`               | `deliverApprovalPrompt()` — sends approval payload to gateway                                                                                                           |
 | `gateway/src/telegram/send.ts`                          | `buildInlineKeyboard()` — renders approval actions as Telegram inline buttons                                                                                           |
 | `gateway/src/telegram/normalize.ts`                     | `callback_query` normalization into `GatewayInboundEvent` (DM-only, drops callbacks without data)                                                                       |
@@ -1013,7 +1013,7 @@ When the LLM emits `[ASK_GUARDIAN: question]` during a voice call, the controlle
 
 5. **Request-code disambiguation**: When a guardian has multiple pending requests across concurrent calls, they prefix their answer with the 6-character hex request code to indicate which question they are answering. This allows unambiguous routing even when questions arrive on the same channel in quick succession.
 
-6. **Expiry sweep**: The daemon's `guardian-expiry-sweep.ts` runs a periodic 60-second sweep that asks the gateway to CAS-expire pending requests past their expiry timestamp (`guardian_requests_sweep_expired`). Expiry notices are sent to all delivery destinations associated with each expired request (`guardian-action-sweep.ts`).
+6. **Expiry sweep**: The daemon's `guardian-expiry-sweep.ts` runs a periodic 60-second sweep that lists past-deadline pending requests (`guardian_requests_list_expired_pending`), runs each row's side effects, and confirms each with the per-request `guardian_requests_expire` CAS. Expiry notices are sent to all delivery destinations associated with each expired request (`guardian-action-sweep.ts`).
 
 7. **One store, many kinds**: Voice questions share the gateway's `guardian_requests` store with every other guardian request, distinguished by `kind` — `tool_approval` and `tool_grant_request` rows gate specific tool invocations, `pending_question` rows carry free-form questions from voice calls that require human input to continue the conversation, and `access_request` rows gate unknown-sender access.
 

package/Dockerfile

@@ -50,6 +50,7 @@ COPY --from=builder --chown=gateway:gateway /app /app
 # Copy source after installing dependencies for better layer caching.
 COPY --chown=gateway:gateway packages/assistant-client /app/packages/assistant-client
 COPY --chown=gateway:gateway packages/ces-client /app/packages/ces-client
+COPY --chown=gateway:gateway packages/environments /app/packages/environments
 COPY --chown=gateway:gateway packages/gateway-client /app/packages/gateway-client
 COPY --chown=gateway:gateway packages/ipc-server-utils /app/packages/ipc-server-utils
 COPY --chown=gateway:gateway packages/service-contracts /app/packages/service-contracts

package/knip.json

@@ -1,13 +1,10 @@
 {
-  "entry": [
-    "src/**/*.test.ts",
-    "src/**/__tests__/**/*.ts",
-    "src/cli/index.ts"
-  ],
+  "entry": ["src/**/*.test.ts", "src/**/__tests__/**/*.ts", "src/cli/index.ts"],
   "project": ["src/**/*.ts"],
   "ignoreDependencies": [
     "@vellumai/assistant-client",
     "@vellumai/ces-client",
+    "@vellumai/environments",
     "@vellumai/gateway-client",
     "@vellumai/ipc-server-utils",
     "@vellumai/service-contracts",

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/package.json

@@ -11,6 +11,7 @@
     "./client-metadata": "./src/client-metadata.ts",
     "./credential-rpc": "./src/credential-rpc.ts",
     "./ingress": "./src/ingress.ts",
+    "./no-response": "./src/no-response.ts",
     "./remote-web-pairing": "./src/remote-web-pairing.ts",
     "./twilio-ingress": "./src/twilio-ingress.ts",
     "./trust-rules": "./src/trust-rules.ts",

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/channels.ts

@@ -66,6 +66,13 @@ export function isChannelId(value: unknown): value is ChannelId {
  * That irregularity is why this is stated rather than derived from the key,
  * and it is stated here because this file already owns what a channel is.
  *
+ * Both senses can hold a user token, which is the sharpest edge. The `slack`
+ * integration's persisted token *is* the installer's user token, held on its
+ * OAuth connection. `slack_channel` holds an optional `user_token` in the
+ * credential store, beside its bot and app tokens. Same words, different
+ * homes, and only the second is a credential-store key: a pasted token is
+ * always the channel's, because the integration's never leaves the exchange.
+ *
  * Deliberately only the key. What fields each credential requires is declared
  * once already, per service, in the gateway's credential specs; restating it
  * here would be a second copy of a different fact.

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/index.ts

@@ -27,6 +27,7 @@ export * from "./handles.js";
 export * from "./rpc.js";
 export * from "./trust-rules.js";
 export * from "./ingress.js";
+export * from "./no-response.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";
 export * from "./url-normalization.js";

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/no-response.ts

@@ -0,0 +1,84 @@
+/**
+ * The `<no_response/>` sentinel: the cross-service convention for a turn
+ * that deliberately produces no user-visible reply.
+ *
+ * The model emits it, the daemon stamps and strips it, channel delivery
+ * suppresses it, and clients hold live-streamed prefixes of it back from
+ * display. One definition here keeps every consumer's parsing identical;
+ * a hand-rolled copy in any one of them is how the case-sensitivity of a
+ * regex drifts.
+ */
+
+/** Matches a message whose entire content is the sentinel. */
+const NO_RESPONSE_ONLY_RE = /^\s*<no_response\s*\/?>\s*$/i;
+
+/**
+ * Whether `text` is nothing but the sentinel: the whole reply is a
+ * deliberate non-response, as opposed to real content with an inline
+ * sentinel mixed in.
+ */
+export function isNoResponseOnlyText(text: string): boolean {
+  return NO_RESPONSE_ONLY_RE.test(text);
+}
+
+/** Matches every sentinel occurrence for stripping it out of mixed content. */
+export const NO_RESPONSE_INLINE_RE = /<no_response\s*\/?>/gi;
+
+/**
+ * Detection variant without the `g` flag: a `g`-flagged regex is stateful
+ * under `.test()` (it resumes from `lastIndex`), so reusing
+ * {@link NO_RESPONSE_INLINE_RE} for detection would alternate between
+ * matches and misses across calls.
+ */
+const NO_RESPONSE_MARKER_RE = new RegExp(NO_RESPONSE_INLINE_RE.source, "i");
+
+/** Whether `text` contains the sentinel anywhere. */
+export function containsNoResponseMarker(text: string): boolean {
+  return NO_RESPONSE_MARKER_RE.test(text);
+}
+
+/** Removes every sentinel occurrence, trimming the leftover whitespace. */
+export function stripNoResponseMarkers(text: string): string {
+  return text.replace(NO_RESPONSE_INLINE_RE, "").trim();
+}
+
+const NO_RESPONSE_SENTINEL_FORMS = [
+  "<no_response/>",
+  "<no_response />",
+  "<no_response>",
+] as const;
+
+/**
+ * Whether `text` could still grow into the sentinel, i.e. it is a leading
+ * substring of one of its forms. Holding on these keeps a slowly-streamed
+ * `<no_response/>` from surfacing as visible partial content.
+ */
+export function isPotentialNoResponsePrefix(text: string): boolean {
+  const lower = text.trim().toLowerCase();
+  if (lower.length === 0) {
+    return false;
+  }
+  return NO_RESPONSE_SENTINEL_FORMS.some((sentinel) =>
+    sentinel.startsWith(lower),
+  );
+}
+
+/**
+ * Whether `text` carries user-visible content worth acting on now. Returns
+ * `false` for empty text, the standalone sentinel, and any prefix that could
+ * still complete into one; returns `true` once real content remains after
+ * stripping inline sentinels.
+ */
+export function hasDeliverableAssistantText(text: string): boolean {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) {
+    return false;
+  }
+  if (NO_RESPONSE_ONLY_RE.test(trimmed)) {
+    return false;
+  }
+  if (isPotentialNoResponsePrefix(trimmed)) {
+    return false;
+  }
+  return stripNoResponseMarkers(trimmed).length > 0;
+}

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

@@ -0,0 +1,21 @@
+{
+  "name": "@vellumai/environments",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./seeds": "./src/seeds.ts",
+    "./shell": "./src/shell.ts",
+    "./test-path-guard": "./src/test-path-guard.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__/cloud-assistant-hub-url.test.ts

@@ -0,0 +1,38 @@
+/**
+ * Pins the environment-to-cloud-hub mapping in one place. Both consumers
+ * (the Capacitor shell's `server.url` and the CLI remote-web edge's
+ * `hubUrl`) read this helper, so this matrix is the single behavioral pin
+ * for the served URLs.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { cloudAssistantHubUrl, SEEDS } from "../index.js";
+
+describe("cloudAssistantHubUrl", () => {
+  test("cloud environments resolve to their own web origin", () => {
+    expect(cloudAssistantHubUrl("production")).toBe(
+      "https://www.vellum.ai/assistant",
+    );
+    expect(cloudAssistantHubUrl("staging")).toBe(
+      "https://staging-assistant.vellum.ai/assistant",
+    );
+  });
+
+  test("every other environment falls back to the dev SPA", () => {
+    for (const name of ["dev", "test", "local", "unknown-env", undefined]) {
+      expect(cloudAssistantHubUrl(name)).toBe(
+        "https://dev-assistant.vellum.ai/assistant",
+      );
+    }
+  });
+
+  test("cloud hub URLs derive from the seed web URLs", () => {
+    for (const name of ["production", "staging"]) {
+      expect(cloudAssistantHubUrl(name)).toBe(
+        `${SEEDS[name].webUrl}/assistant`,
+      );
+    }
+    expect(cloudAssistantHubUrl("local")).toBe(`${SEEDS.dev.webUrl}/assistant`);
+  });
+});

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

@@ -0,0 +1,98 @@
+/**
+ * Tests for reading an install layout: telling a repo checkout from an
+ * installed package, and locating the `assistant` command that ships with an
+ * install.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { findAssistantCommand, isRepoCheckoutPath } from "../index.js";
+
+let root: string;
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "install-layout-"));
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+/** Create `<nodeModulesDir>/.bin/assistant` and return its path. */
+function seedCommand(nodeModulesDir: string): string {
+  const binDir = join(nodeModulesDir, ".bin");
+  mkdirSync(binDir, { recursive: true });
+  const command = join(binDir, "assistant");
+  writeFileSync(command, "#!/usr/bin/env bun\n");
+  return command;
+}
+
+describe("isRepoCheckoutPath", () => {
+  test("an installed package is not a checkout", () => {
+    expect(
+      isRepoCheckoutPath(
+        "/Users/x/Library/Application Support/@vellumai/macos/cli/latest/node_modules/@vellumai/assistant/src/index.ts",
+      ),
+    ).toBe(false);
+  });
+
+  test("a repo checkout is", () => {
+    expect(
+      isRepoCheckoutPath("/Users/x/dev/vellum/assistant/src/index.ts"),
+    ).toBe(true);
+  });
+
+  test("a directory merely named node_modules-ish is not enough", () => {
+    expect(
+      isRepoCheckoutPath("/Users/x/node_modules_backup/a/src/index.ts"),
+    ).toBe(true);
+  });
+});
+
+describe("findAssistantCommand", () => {
+  test("finds the command shipped beside an installed package", () => {
+    const nodeModules = join(root, "cli", "latest", "node_modules");
+    const command = seedCommand(nodeModules);
+    const path = join(nodeModules, "@vellumai", "assistant", "src", "index.ts");
+
+    expect(findAssistantCommand(path)).toBe(command);
+  });
+
+  test("prefers a nested install over a hoisted one", () => {
+    const outer = join(root, "node_modules");
+    const outerCommand = seedCommand(outer);
+    const inner = join(outer, "vellum", "node_modules");
+    const innerCommand = seedCommand(inner);
+    const path = join(inner, "@vellumai", "assistant", "src", "index.ts");
+
+    expect(findAssistantCommand(path)).toBe(innerCommand);
+    expect(innerCommand).not.toBe(outerCommand);
+  });
+
+  test("falls back to a hoisted install when the nested one has no command", () => {
+    const outer = join(root, "node_modules");
+    const outerCommand = seedCommand(outer);
+    const inner = join(outer, "vellum", "node_modules");
+    mkdirSync(inner, { recursive: true });
+    const path = join(inner, "@vellumai", "assistant", "src", "index.ts");
+
+    expect(findAssistantCommand(path)).toBe(outerCommand);
+  });
+
+  test("returns null for a repo checkout", () => {
+    expect(
+      findAssistantCommand(join(root, "assistant", "src", "index.ts")),
+    ).toBeNull();
+  });
+
+  test("returns null when the install ships no assistant command", () => {
+    const nodeModules = join(root, "node_modules");
+    mkdirSync(join(nodeModules, ".bin"), { recursive: true });
+    const path = join(nodeModules, "@vellumai", "assistant", "src", "index.ts");
+
+    expect(findAssistantCommand(path)).toBeNull();
+  });
+});

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:
+ * environment types, constants, and small helpers over node builtins, 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 dependency-free 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/__tests__/test-path-guard.test.ts

@@ -0,0 +1,89 @@
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import {
+  assertTestPathIsEphemeral,
+  canonicalizePathThroughExistingParent,
+  isBunTestProcess,
+} from "../test-path-guard.js";
+
+const OPTIONS = {
+  allowEnvVar: "TEST_PATH_GUARD_ALLOW",
+  runHint: "Run tests from the package root.",
+};
+
+describe("isBunTestProcess", () => {
+  test("detects this bun test run", () => {
+    expect(isBunTestProcess()).toBe(true);
+  });
+});
+
+describe("canonicalizePathThroughExistingParent", () => {
+  test("resolves symlinks on the deepest existing ancestor", () => {
+    const root = mkdtempSync(join(tmpdir(), "test-path-guard-"));
+    try {
+      const target = join(root, "target");
+      mkdirSync(target);
+      const link = join(root, "link");
+      symlinkSync(target, link, "dir");
+      expect(
+        canonicalizePathThroughExistingParent(join(link, "missing", "leaf")),
+      ).toBe(
+        join(canonicalizePathThroughExistingParent(target), "missing", "leaf"),
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("returns the input path when no ancestor exists", () => {
+    expect(canonicalizePathThroughExistingParent("/nonexistent-root-x/y")).toBe(
+      "/nonexistent-root-x/y",
+    );
+  });
+});
+
+describe("assertTestPathIsEphemeral", () => {
+  test("allows paths under tmpdir, existing or not", () => {
+    expect(() =>
+      assertTestPathIsEphemeral(join(tmpdir(), "guard-missing", "x"), OPTIONS),
+    ).not.toThrow();
+  });
+
+  test("refuses paths outside tmpdir, naming the escape hatch and hint", () => {
+    delete process.env[OPTIONS.allowEnvVar];
+    const dir = join(homedir(), "test-path-guard-live");
+    expect(() => assertTestPathIsEphemeral(dir, OPTIONS)).toThrow(
+      /Refusing to use[\s\S]*package root[\s\S]*TEST_PATH_GUARD_ALLOW/,
+    );
+  });
+
+  test("refuses a tmpdir symlink that resolves outside tmpdir", () => {
+    delete process.env[OPTIONS.allowEnvVar];
+    const link = join(tmpdir(), `test-path-guard-escape-${process.pid}`);
+    rmSync(link, { force: true });
+    symlinkSync(homedir(), link);
+    try {
+      expect(() => assertTestPathIsEphemeral(link, OPTIONS)).toThrow(
+        /Refusing to use/,
+      );
+    } finally {
+      rmSync(link, { force: true });
+    }
+  });
+
+  test("the allow env var bypasses the guard, per call", () => {
+    const dir = join(homedir(), "test-path-guard-optout");
+    process.env[OPTIONS.allowEnvVar] = "1";
+    try {
+      expect(() => assertTestPathIsEphemeral(dir, OPTIONS)).not.toThrow();
+    } finally {
+      delete process.env[OPTIONS.allowEnvVar];
+    }
+    expect(() => assertTestPathIsEphemeral(dir, OPTIONS)).toThrow(
+      /Refusing to use/,
+    );
+  });
+});

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

@@ -0,0 +1,22 @@
+/**
+ * @vellumai/environments: the single source of truth for how a Vellum install
+ * is laid out and which deployment environment it belongs to.
+ *
+ * Two things live here:
+ *
+ *   - The known deployment environments (names, platform/web URLs, per-service
+ *     port blocks). The Swift client mirrors the same set in
+ *     `VellumEnvironment.swift`.
+ *   - Install layout: whether a runtime is a repo checkout or an installed
+ *     package, and where the `assistant` command it ships lives.
+ *
+ * Consumed by the CLI, the assistant daemon, and the local-mode host library
+ * so each answer is defined exactly once on the TS side.
+ *
+ * This is the lowest layer of the shared-packages hierarchy and stays a leaf:
+ * types, constants, and small helpers over node builtins, with no runtime
+ * dependencies of its own. See `__tests__/package-boundary.test.ts`.
+ */
+export * from "./types.js";
+export * from "./seeds.js";
+export * from "./install-layout.js";

package/node_modules/@vellumai/environments/src/install-layout.ts

@@ -0,0 +1,49 @@
+/**
+ * Reading the layout a Vellum runtime is installed in.
+ *
+ * The daemon is started either from a developer's repo checkout or from an
+ * installed npm package (`<install>/node_modules/@vellumai/assistant/src/
+ * index.ts`, which is what the desktop app runs). The CLI needs the layout to
+ * decide whether a launch is a dev run and what to put on the daemon's PATH;
+ * the daemon needs it to decide what to install as the `assistant` command.
+ * Both ask the same two questions, so they ask them here.
+ */
+
+import { existsSync } from "node:fs";
+import { join, sep } from "node:path";
+
+const NODE_MODULES_SEGMENT = `${sep}node_modules${sep}`;
+
+/**
+ * Whether `path` sits in a developer's repo checkout rather than inside an
+ * installed package.
+ */
+export function isRepoCheckoutPath(path: string): boolean {
+  return !path.includes(NODE_MODULES_SEGMENT);
+}
+
+/**
+ * The `assistant` command shipped with the install that contains `path`, or
+ * null when there is none (a repo checkout, or an install whose dependency
+ * graph omits the package declaring the bin).
+ *
+ * Searches innermost `node_modules` outward, since a nested install shadows a
+ * hoisted one.
+ */
+export function findAssistantCommand(path: string): string | null {
+  let index = path.lastIndexOf(NODE_MODULES_SEGMENT);
+
+  while (index !== -1) {
+    const nodeModulesDir = path.slice(
+      0,
+      index + NODE_MODULES_SEGMENT.length - 1,
+    );
+    const command = join(nodeModulesDir, ".bin", "assistant");
+    if (existsSync(command)) {
+      return command;
+    }
+    index = path.lastIndexOf(NODE_MODULES_SEGMENT, index - 1);
+  }
+
+  return null;
+}