@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/ARCHITECTURE.md

@@ -67,8 +67,10 @@ All HTTP API requests use a single `Authorization: Bearer <jwt>` header for auth
 | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
 | `actor_client_v1`    | `chat.{read,write}`, `approval.{read,write}`, `settings.{read,write}`, `attachments.{read,write}`, `calls.{read,write}`, `feature_flags.{read,write}` | Desktop, CLI clients                         |
 | `gateway_ingress_v1` | `ingress.write`, `internal.write`                                                                                                                     | Gateway channel inbound + webhook forwarding |
-| `gateway_service_v1` | `settings.read`, `settings.write`, `internal.write`                                                                                                   | Gateway service-to-daemon calls              |
-| `internal_v1`        | `internal.all`                                                                                                                                        | Internal service connections                 |
+| `gateway_service_v1` | `chat.{read,write}`, `settings.{read,write}`, `attachments.{read,write}`, `internal.write`                                                            | Gateway service-to-daemon calls              |
+| `local_v1`           | `local.all`                                                                                                                                           | Local (loopback) conversation sessions       |
+| `speech_relay_v1`    | `speech.relay`                                                                                                                                        | Daemon dial of the gateway speech relay only |
+| `ui_page_v1`         | `settings.read`                                                                                                                                       | Served UI pages                              |
 
 **Identity lifecycle:**
 
@@ -836,7 +838,7 @@ graph LR
         JOBS["memory_jobs<br/>───────────────<br/>Async task queue<br/>Types: embed, extract,<br/>summarize, backfill, cleanup<br/>Status: pending → running →<br/>completed | failed"]
         ATT["attachments<br/>───────────────<br/>base64-encoded file data<br/>mime_type, size_bytes<br/>Linked to messages via<br/>message_attachments join"]
         REM["reminders<br/>───────────────<br/>One-time scheduled reminders<br/>label, message, fireAt<br/>mode: notify | execute<br/>status: pending → fired | cancelled<br/>routing_intent: single_channel |<br/>multi_channel | all_channels<br/>routing_hints_json (free-form)"]
-        SCHED_JOBS["cron_jobs (recurrence schedules)<br/>───────────────<br/>Recurring schedule definitions<br/>cron_expression: cron or RRULE string<br/>schedule_syntax: 'cron' | 'rrule'<br/>timezone, message, next_run_at<br/>enabled, retry_count<br/>Legacy alias: scheduleJobs"]
+        SCHED_JOBS["cron_jobs (recurrence schedules)<br/>───────────────<br/>Recurring schedule definitions<br/>cron_expression: cron or RRULE string<br/>schedule_syntax: 'cron' | 'rrule'<br/>timezone, message, next_run_at<br/>enabled, retry_count<br/>source_key: plugin-declared provenance<br/>definition_hash, user_enabled<br/>Legacy alias: scheduleJobs"]
         SCHED_RUNS["cron_runs (schedule runs)<br/>───────────────<br/>Execution history per schedule<br/>job_id (FK → cron_jobs)<br/>status: ok | error<br/>duration_ms, output, error<br/>Legacy alias: scheduleRuns"]
         TASKS["tasks<br/>───────────────<br/>Reusable prompt templates<br/>title, Handlebars template<br/>inputSchema, contextFlags<br/>requiredTools, status"]
         TASK_RUNS["task_runs<br/>───────────────<br/>Execution history per task<br/>taskId (FK → tasks)<br/>conversationId, status<br/>startedAt, finishedAt, error"]
@@ -861,6 +863,59 @@ graph LR
 
 ---
 
+## Plugin-Declared Schedules: Declaration → Reconciler → cron_jobs
+
+Plugins contribute recurring schedules as a surface: directories under
+`<pluginDir>/schedules/`, each a `<name>/` holding `config.json` plus
+exactly one `index.md` (runs as `execute`) or `index.sh` (runs as `script`)
+entrypoint. Ambiguity fails closed: a file sitting directly under
+`schedules/`, zero/multiple/unsupported entrypoints, and malformed config
+produce per-schedule `DeclarationError`s without affecting siblings
+(`src/schedule/plugin-schedule-declarations.ts`).
+
+A level-based reconciler (`src/schedule/plugin-schedule-reconciler.ts`)
+converges declarations into ordinary `cron_jobs` rows keyed by the nullable
+`source_key` column (`plugin:<plugin>/<name>`). Rows with `source_key IS
+NULL` are imperative schedules the reconciler never touches. Triggers: a
+startup pass in `daemon/lifecycle.ts` (after plugin init, before the
+scheduler starts), the end of `reconcilePluginSourcesNow()` in
+`plugins/mtime-cache.ts` (install/uninstall/upgrade and sentinel-driven
+changes), the plugin enable/disable routes, and a 60s backstop sweep
+registered with the HTTP server's background sweeps.
+
+Reconcile lag never lets a disabled plugin run. The disable path writes a
+`.disabled` sentinel that only a reconcile pass turns into disarmed rows, so
+the scheduler re-reads the sentinel at fire time and records a skipped run
+instead of executing a claimed row whose plugin is off. Run-now applies the
+same boundary through `declarationExistsOnDisk`, which also covers a plugin
+whose manifest no longer parses, a declaration directory that is gone, and a
+plugin root or declaration directory resolving outside the tree it belongs to
+(the same `isInsidePluginRoot` containment the loader applies before importing
+a plugin).
+
+A declaration that stops parsing keeps its execute row armed on the message
+already stored in the row, but disarms its script rows: a script row fires its
+entrypoint by absolute path, so leaving it armed would run the very `index.sh`
+the parser rejected. Those rows re-arm on the pass after the declaration parses
+again.
+
+Ownership boundaries: the reconciler owns definition columns (expression,
+timezone, message/script, retry policy, `definition_hash`); the execution
+engine owns runtime columns (`next_run_at`, `status`, `last_*`,
+`retry_count`) and its latches are never overridden; the user owns
+`user_enabled`, a sticky override consulted when computing effective
+`enabled`. Nothing ever writes to plugin files. Execution itself is
+unchanged: declared rows fire through the same `claimDueSchedules` path as
+imperative ones.
+
+Consent and surfacing: CLI install/upgrade list declared schedules and
+prompt before finalizing; unattended daemon-route installs are covered by
+`schedule.declared` arrival notifications, with `schedule.definition_changed`
+and `schedule.definition_error` covering upgrades and broken declarations
+(events registered in `notifications/signal.ts`, deterministic templates in
+`notifications/copy-composer.ts`). Settings routes, CLI, and web render
+plugin-sourced rows read-only except the enabled toggle.
+
 ---
 
 ## Web Server — Connection Modes

package/docs/trusted-contact-access.md

@@ -43,6 +43,9 @@ Design doc defining how unknown users gain access to a Vellum assistant via chan
 5. **On approval the gateway mints a verification session.** The decide op carries a `mint_outbound_session` outcome; inside the decide transaction the gateway (`gateway/src/verification/session-service.ts`) generates a 6-digit code, persists only its SHA-256 hash in `channel_verification_sessions` (identity-bound to the requester, `verificationPurpose: 'trusted_contact'`), and returns the raw secret to the daemon in the decide response for delivery.
 6. **The code is delivered.** The daemon delivers the code to the guardian's verified channel (ephemeral + DM on Slack shared channels so other members never see it). On Slack the code is also DM'd straight to the requester; on other channels the guardian relays it out-of-band (in person, text message, phone call). That out-of-band transfer is the trust anchor: it proves the requester has a real-world relationship with the guardian.
 7. **Requester enters the code** back to the assistant on the same channel. The **gateway** intercepts bare verification codes at ingress (`gateway/src/verification/text-verification.ts`) whenever an interceptable session exists for that channel — the daemon never sees verification code messages.
+
+   On Discord the code is delivered to, and answered in, a DM (`gateway/src/discord/admit.ts` admits DMs on their own lane). A bare code typed into a guild channel is dropped by the mention gate before it reaches the intercept, so it is never consumed and never reaches the agent.
+
 8. **Gateway verifies the code and activates the user.** `validateAndConsumeSession()` checks the rate limit, hashes the code, matches it against a live session, verifies identity binding, atomically consumes the session, then applies the trusted-contact side effects: `applyTrustedContactSideEffects()` upserts the verified channel into the gateway ACL with `status: 'active'`, `policy: 'allow'` and mirrors the contact identity to the assistant DB. A blocked/revoked authoritative gateway row rejects the verification even when the code matched. The gateway delivers the deterministic success reply.
 9. **All subsequent messages are accepted normally.** The gateway stamps an allow verdict and the daemon processes the message.
 
@@ -65,11 +68,12 @@ requested -> pending_guardian -> verification_pending -> active | denied | expir
 
 Identity binding ensures the verification code can only be consumed by the intended recipient on the intended channel. The binding fields are set on the gateway `channel_verification_sessions` record when the session is created; the check itself is `checkIdentityMatch` (`gateway/src/verification/identity-match.ts`).
 
-| Channel   | Identity fields                                                                  | Binding behavior                                                                                                                                                                                                           |
-| --------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Telegram  | `expectedExternalUserId` = Telegram user ID, `expectedChatId` = Telegram chat ID | Both are taken from the original denied message's metadata. The `identityBindingStatus` is `'bound'`. Verification requires the actor's user ID or chat ID to match (user ID required when both are set on a shared chat). |
-| Voice     | `expectedPhoneE164` = phone number in E.164 format                               | Phone-based identity binding. Verification requires the caller's number to match the expected phone.                                                                                                                       |
-| Bootstrap | none yet (`identityBindingStatus: 'pending_bootstrap'`)                          | Unbound deep-link sessions use a 32-byte hex token instead of a numeric code; the identity is bound when the token is redeemed (`verification_sessions_bind_identity`).                                                    |
+| Channel   | Identity fields                                                                  | Binding behavior                                                                                                                                                                                                                                                                                                         |
+| --------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Telegram  | `expectedExternalUserId` = Telegram user ID, `expectedChatId` = Telegram chat ID | Both are taken from the original denied message's metadata. The `identityBindingStatus` is `'bound'`. Verification requires the actor's user ID or chat ID to match (user ID required when both are set on a shared chat).                                                                                               |
+| Voice     | `expectedPhoneE164` = phone number in E.164 format                               | Phone-based identity binding. Verification requires the caller's number to match the expected phone.                                                                                                                                                                                                                     |
+| Discord   | `expectedExternalUserId` = Discord user snowflake. `expectedChatId` is unset on the guardian-initiated and trusted-contact paths, and is the originating guild channel on the access-request approval path (`mint_outbound_session`), which sets it for every channel alike. | The code is delivered to a DM and answered there, but the DM channel does not exist until it is opened, so those two paths have no chat id to record at mint time. Where the approval path does set one, it is a room rather than an identity and never becomes a sufficient credential on its own: `checkIdentityMatch` requires the `expectedExternalUserId` match whenever both fields are set. That path also writes the room into `destinationAddress`, where it describes nothing the code is ever sent to (see LUM-3110). |
+| Bootstrap | none yet (`identityBindingStatus: 'pending_bootstrap'`)                          | Unbound deep-link sessions use a 32-byte hex token instead of a numeric code; the identity is bound when the token is redeemed (`verification_sessions_bind_identity`).                                                                                                                                                  |
 
 **Anti-oracle invariant:** When identity verification fails, the error message is identical to the "invalid or expired code" message. This prevents attackers from distinguishing between a wrong code and a wrong identity, which would leak information about which identities have pending sessions.
 

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

@@ -40,3 +40,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.",
       );
     }