@vellumai/assistant 0.11.2 → 0.11.3-dev.202608080427.92f668a

package/docs/vellum-doctor.md

@@ -0,0 +1,195 @@
+# Vellum Doctor
+
+Vellum Doctor is a platform-hosted diagnostic tool for investigating problems with a Vellum assistant.
+
+> **Status:** Beta. Vellum Doctor is available in the web client for platform-hosted assistants; it is not available for self-hosted assistants.
+
+## What it does
+
+Doctor provides a separate diagnostic session where a guardian can describe an issue and receive an investigation that may include:
+
+- Plain-language explanations of what the Doctor found.
+- Tool calls with expandable technical details and outputs.
+- Requests for approval before an operation runs.
+- A backup prompt before an operation that may modify the assistant.
+- Feedback prompts when an issue may need attention from the Vellum team.
+- A session transcript that can be copied for follow-up or support.
+
+Doctor is separate from the assistant's normal conversation. It is a support and diagnosis surface, not another assistant that builds a long-term relationship with the guardian.
+
+## When to use it
+
+Open Doctor when an assistant is not behaving as expected, especially when the cause could be a runtime problem, an integration or credential problem, a missing capability, a failed scheduled action, or a permission boundary.
+
+The web client may show a **Go to Doctor** action in an operational error notice. Doctor can also be opened from the **Doctor** tab under the assistant's debug settings.
+
+### Open Doctor from chat
+
+The web client supports a slash command that opens the Doctor panel:
+
+```text
+/doctor
+```
+
+You can include the first message after the command:
+
+```text
+/doctor My assistant stopped responding after I connected Slack
+```
+
+The command navigates to Doctor instead of sending the text as a normal assistant turn. On a self-hosted assistant, Doctor is unavailable and the command does not start a Doctor session.
+
+## Session lifecycle
+
+A Doctor session follows this flow:
+
+1. The web client creates a diagnostic session for the active assistant.
+2. Doctor sends a greeting and opens a live event stream.
+3. The guardian describes the issue and can send follow-up messages while the session is active.
+4. Doctor streams assistant messages, tool activity, approval requests, backup prompts, and errors into the panel.
+5. The session ends with either `completed` or `error` status.
+6. The guardian can start a new session after a terminal state.
+
+The web client can load the most recent persisted session when the Doctor panel opens. An active session can be resumed, including pending approval or backup prompts, and completed sessions remain available as history.
+
+## Approval and backup prompts
+
+Doctor can ask for confirmation before running an operation.
+
+- **Allow once** approves the requested operation for the current prompt.
+- **Always Allow** is available for `exec_command` requests and approves future execution requests in that session.
+- **Deny** rejects the requested operation.
+- **Show details** reveals the tool name, description, and input that Doctor received.
+
+Before an operation that may modify the assistant, Doctor can ask whether to create a backup first:
+
+- **Back up** creates the backup before continuing.
+- **Skip** continues without that backup.
+
+Approval and backup prompts are part of the session transcript, so the guardian can see which operations were proposed and how they were handled.
+
+## Session history and transcripts
+
+Doctor sessions are persisted against the assistant that they diagnose. The web client can retrieve the newest sessions and the ordered message ledger for a selected session.
+
+A persisted session includes:
+
+- Lifecycle status: `active`, `completed`, or `error`.
+- Ordered user and Doctor messages.
+- Tool calls and tool results.
+- Approval, backup, feedback, status, and error entries.
+- Message timestamps and counts.
+- Token and estimated-cost totals returned by the platform API.
+
+The **Copy Session** action serializes the visible session into text. Doctor's idle panel also warns that Doctor logs may be temporarily stored, so guardians should avoid entering secrets that are not necessary for diagnosis.
+
+## Feedback and support handoff
+
+Doctor can show a feedback prompt when the investigation identifies an issue that may be useful to the Vellum team. The feedback flow can include the Doctor session ID and a transcript file, subject to the diagnostics choice in the feedback form.
+
+Sharing feedback is separate from approving a Doctor operation. A guardian can continue describing the issue while the feedback prompt is present.
+
+## API reference
+
+The platform API exposes Doctor under the assistant-scoped routes below. Requests use the same authentication options as the surrounding platform API.
+
+| Operation        | Route                                                                           | Purpose                                                    |
+| ---------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| List history     | `GET /v1/assistants/{assistant_id}/doctor/history/`                             | List persisted sessions, newest first.                     |
+| Retrieve history | `GET /v1/assistants/{assistant_id}/doctor/history/{doctor_session_id}/`         | Retrieve one session and its ordered message ledger.       |
+| Create session   | `POST /v1/assistants/{assistant_id}/doctor/sessions/`                           | Create a new diagnostic session and return its session ID. |
+| Stream events    | `GET /v1/assistants/{assistant_id}/doctor/sessions/{session_id}/events/`        | Receive Doctor events over Server-Sent Events.             |
+| Send message     | `POST /v1/assistants/{assistant_id}/doctor/sessions/{session_id}/messages/`     | Send a message to an active session.                       |
+| Record outcome   | `POST /v1/assistants/{assistant_id}/doctor/sessions/{session_id}/user-outcome/` | Record whether Doctor solved the problem.                  |
+| Delete session   | `DELETE /v1/assistants/{assistant_id}/doctor/sessions/{session_id}/`            | End and clean up a session.                                |
+
+### Create a session
+
+A successful create request returns:
+
+```json
+{
+  "session_id": "doctor-session-id"
+}
+```
+
+### Send a message
+
+The message body requires non-empty `content` and can include an optional `source_event_id` for replay-safe delivery:
+
+```json
+{
+  "content": "My assistant cannot send messages to Slack"
+}
+```
+
+A successful request is accepted with HTTP `202` while the response arrives on the event stream.
+
+### Record the user outcome
+
+When Doctor asks whether it solved the problem, submit the answer to the session's outcome route:
+
+```json
+{
+  "resolved": true
+}
+```
+
+Use `false` when the problem was not resolved. The endpoint returns `200`, records the latest answer for the session, and works for both active and completed sessions.
+
+### Event types
+
+The event stream validates and handles these event types:
+
+| Event                 | Meaning                                                         |
+| --------------------- | --------------------------------------------------------------- |
+| `message`             | A complete Doctor message.                                      |
+| `message_delta`       | A streamed part of a Doctor message.                            |
+| `tool_call`           | Doctor started a tool operation.                                |
+| `tool_result`         | A tool operation returned output, including whether it failed.  |
+| `approval_required`   | Doctor is waiting for an approval response.                     |
+| `backup_prompt`       | Doctor is asking whether to create a backup before continuing.  |
+| `feedback_prompt`     | Doctor is offering a feedback handoff.                          |
+| `user_outcome_prompt` | Doctor is asking whether it solved the guardian's problem.      |
+| `status`              | The session is active, completed, or in an error state.         |
+| `error`               | The session encountered an error with a human-readable message. |
+
+Malformed events and unknown event types are ignored by the web client rather than being treated as trusted Doctor output.
+
+## Failure states and recovery
+
+### No assistant is selected
+
+Doctor cannot start without an active assistant. Hatch or select an assistant, then reopen the Doctor panel.
+
+### Doctor is unavailable
+
+Doctor is platform-hosted. Self-hosted assistants do not expose the Doctor tab or the `/doctor` command.
+
+### Monthly session limit
+
+The platform can reject session creation when the available Doctor sessions for the month have been used. The web client tells the guardian to try again next month.
+
+### Service or connection failure
+
+Session creation, message delivery, and event streaming can fail when the Doctor service or platform proxy is unavailable. The panel surfaces the returned error and ends the session when it cannot recover.
+
+The event stream retries recoverable interruptions with a bounded reconnect policy. If the session has expired, its event history cannot be replayed, or the stream remains idle, the panel asks the guardian to start a new session.
+
+### A tool operation fails
+
+A failed tool result is shown in the transcript with its technical output. Doctor can continue investigating, ask for another action, or end the session with an error. A failed operation does not become a successful diagnosis merely because the session is still open.
+
+## Source map
+
+The implementation currently lives in the web client and platform API contract:
+
+- `clients/web/src/domains/settings/pages/debug-page.tsx` exposes the Doctor tab.
+- `clients/web/src/domains/settings/components/panels/doctor-panel.tsx` owns session creation, messaging, history, cleanup, and the panel UI.
+- `clients/web/src/domains/settings/components/panels/use-doctor-sse.ts` owns the event stream, validation boundary, reconnect behavior, and replay handling.
+- `clients/web/src/domains/settings/components/panels/doctor-event-schema.ts` defines the validated event contract.
+- `clients/web/src/domains/settings/components/panels/doctor-event-handlers.ts` maps events into visible session entries.
+- `clients/web/src/domains/settings/components/panels/doctor-history.ts` maps persisted messages and serializes copied transcripts.
+- `clients/web/openapi-schemas/platform.yaml` defines the assistant-scoped Doctor routes and persisted session schemas.
+
+The Vellum Assistant runtime does not provide a local Doctor CLI command. Doctor is a web and platform capability, not a command run inside a self-hosted assistant.

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

@@ -6,6 +6,16 @@
  * assistant through (Slack, Telegram, WhatsApp, phone, …) plus a couple of
  * internal ids (`vellum` for native app conversations, `platform` for the
  * internal control plane). This is the single source of truth for that set:
+ *
+ * One id, `plugin`, does not name a surface: it names *every* surface a plugin
+ * brings. A plugin channel's real identity is the plugin, which is workspace
+ * state and cannot be a compile-time union member, so the plugin name travels
+ * in `sourceMetadata.plugin` and is prefixed onto every external id the gateway
+ * forwards (`imessage:+15551234567`). Two plugins therefore share a channel
+ * row — one admission floor, one set of channel-wide defaults — while their
+ * conversations, contacts, and trust records stay disjoint. See
+ * `gateway/src/channels/plugin-inbound.ts` for what that concedes.
+ *
  * the assistant adopts it wholesale as its `ChannelId`, and the gateway
  * asserts its own (narrower) inbound list is a subset of it so the two sides
  * cannot silently drift.
@@ -30,6 +40,7 @@ export const CHANNEL_IDS = [
   "platform",
   "a2a",
   "discord",
+  "plugin",
 ] as const;
 
 export type ChannelId = (typeof CHANNEL_IDS)[number];
@@ -40,3 +51,42 @@ export function isChannelId(value: unknown): value is ChannelId {
     (CHANNEL_IDS as readonly string[]).includes(value)
   );
 }
+
+/**
+ * The provider key holding each channel's bot credential.
+ *
+ * Two senses of "connected" share the provider registry: a provider the user
+ * authorized so the assistant can act **as them** (`slack`, `discord`,
+ * `google`), and a bot credential letting people reach the assistant **as
+ * itself**. Nothing in a provider key says which, and the naming actively
+ * misleads: `slack` and `discord` name the user integration while their bots
+ * take a `_channel` suffix, yet `telegram` *is* the bot, because Telegram has
+ * no user-identity integration.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * Channels absent from this map reach the assistant without a bot credential
+ * of their own: `phone` through the voice provider, `vellum` and `platform`
+ * internally.
+ */
+export const CHANNEL_BOT_PROVIDER = {
+  slack: "slack_channel",
+  discord: "discord_channel",
+  telegram: "telegram",
+} as const satisfies Partial<Record<ChannelId, string>>;
+
+/**
+ * Whether a provider key names a bot the assistant is reached through, rather
+ * than a grant letting it act as the user. This is the "which sense of
+ * connected" question, for any provider key.
+ */
+export function isChannelBotProvider(providerKey: string): boolean {
+  return (Object.values(CHANNEL_BOT_PROVIDER) as readonly string[]).includes(
+    providerKey,
+  );
+}

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

@@ -20,6 +20,16 @@ export function normalizePublicBaseUrl(value: unknown): string | undefined {
   return normalized.length > 0 ? normalized : undefined;
 }
 
+/**
+ * Application close code the gateway's velay bridge sends to proxied
+ * WebSockets when the tunnel itself is lost (velay disconnect, gateway
+ * shutdown). A dedicated code because the natural 1001 (going away) cannot
+ * be sent through the JS `close()` API (the bridge would remap it to a
+ * misleading 4001), and Bun's WebSocket client drops close reasons, so the
+ * code is the only signal that survives the relay to the daemon.
+ */
+export const GATEWAY_TUNNEL_LOST_WS_CLOSE_CODE = 4801;
+
 export function normalizeHttpPublicBaseUrl(value: unknown): string | undefined {
   if (typeof value !== "string") return undefined;
   const trimmed = value.trim();

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/remote-web-pairing.ts

@@ -21,6 +21,12 @@
  * `Date#toISOString()`.
  */
 
+/**
+ * Pairing-challenge TTL in milliseconds (10 minutes): the gateway's challenge
+ * store enforces it and the `vellum pair` CLI renders it in user-facing copy.
+ */
+export const REMOTE_WEB_PAIRING_CODE_TTL_MS = 10 * 60 * 1000;
+
 /** `POST /v1/remote-web/pairing-challenge` request body. */
 export interface RemoteWebPairingChallengeRequest {
   /** Public https base URL the scanning device can reach the assistant at. */

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

@@ -40,4 +40,5 @@ export {
   type CesRpcClient,
   type CesRpcClientConfig,
   type CesRpcHandshakeOptions,
+  type CesRpcLogger,
 } from "./rpc-client.js";

package/node_modules/@vellumai/ces-client/src/rpc-client.ts

@@ -69,11 +69,23 @@ interface PendingRequest {
 // Client configuration
 // ---------------------------------------------------------------------------
 
+/** Minimal logger interface. Callers can supply pino, console, etc. */
+export interface CesRpcLogger {
+  info(obj: Record<string, unknown>, msg: string): void;
+  info(msg: string): void;
+}
+
 export interface CesRpcClientConfig {
   /** Timeout for individual RPC requests (ms). Default: 30 000 */
   requestTimeoutMs?: number;
   /** Timeout for the initial handshake (ms). Default: 10 000 */
   handshakeTimeoutMs?: number;
+  /**
+   * Optional logger for lifecycle transitions (handshake accepted, close).
+   * These transitions are otherwise invisible, which made a stuck credential
+   * backend hard to diagnose.
+   */
+  logger?: CesRpcLogger;
 }
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
@@ -154,12 +166,15 @@ export function createCesRpcClient(
     config?.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
   const handshakeTimeoutMs =
     config?.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS;
+  const logger = config?.logger;
 
   const sessionId = randomUUID();
   let requestCounter = 0;
   let ready = false;
-  let inflightHandshake: Promise<{ accepted: boolean; reason?: string }> | null =
-    null;
+  let inflightHandshake: Promise<{
+    accepted: boolean;
+    reason?: string;
+  }> | null = null;
 
   const pending = new Map<string, PendingRequest>();
 
@@ -380,6 +395,7 @@ export function createCesRpcClient(
 
         if (ack.accepted) {
           ready = true;
+          logger?.info("CES RPC client handshake accepted; ready for calls");
         }
 
         return { accepted: ack.accepted, reason: ack.reason };
@@ -413,6 +429,7 @@ export function createCesRpcClient(
     close(): void {
       rejectAllPending(new CesTransportError("CES client closed"));
       ready = false;
+      logger?.info("CES RPC client closed");
       transport.close();
     },
   };

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

@@ -5,7 +5,8 @@
   "license": "MIT",
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./seeds": "./src/seeds.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

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

@@ -1,10 +1,10 @@
 /**
  * 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.
+ * 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/*`
@@ -79,7 +79,7 @@ describe("package boundary", () => {
       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" +
+          "\n\n@vellumai/environments is a dependency-free leaf and must\n" +
           "import only node builtins and its own relative modules.",
       );
     }

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

@@ -1,11 +1,22 @@
 /**
- * @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`.
+ * @vellumai/environments: the single source of truth for how a Vellum install
+ * is laid out and which deployment environment it belongs to.
  *
- * Intentionally free of runtime dependencies: pure types and constants only.
+ * 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;
+}

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

@@ -24,6 +24,35 @@ function portBlock(base: number): PortMap {
   };
 }
 
+/**
+ * Base URL of the cloud-hosted assistant SPA (the "hub") for a deployment
+ * environment. The Capacitor mobile shell bakes this into native builds as
+ * `server.url`, and the CLI's remote-web edge stamps it into the served
+ * config as `hubUrl`, so the environment-to-hub mapping lives here exactly
+ * once.
+ *
+ * Only the cloud deployments (production, staging) serve the hosted SPA at
+ * their own web origin; every other environment (dev, test, local, unknown)
+ * falls back to the dev SPA, whose host serves remote clients that cannot
+ * reach a local or per-developer web URL.
+ *
+ * The `/assistant` suffix is deliberate: booting on the bare host lands on
+ * the marketing page, whose CTA redirects to `www.vellum.ai/assistant` and
+ * bounces non-prod shells off their own host.
+ *
+ * NOTE: this module is loaded by Capacitor's single-file TS config loader
+ * (via the `@vellumai/environments/seeds` subpath), which cannot follow the
+ * package index's `.js`-suffixed runtime re-exports. Keep this file's
+ * imports type-only so it stays loadable on its own.
+ */
+export function cloudAssistantHubUrl(envName: string | undefined): string {
+  const seed =
+    envName === "production" || envName === "staging"
+      ? SEEDS[envName]
+      : SEEDS.dev;
+  return `${seed.webUrl}/assistant`;
+}
+
 /**
  * Built-in environment definitions and the source of truth for the
  * set of known environment names.