@vellumai/assistant 0.7.1 → 0.7.3

package/src/inbound/public-ingress-urls.ts

@@ -27,17 +27,30 @@
  * All public-facing ingress URL construction is centralized here.
  */
 
+import {
+  buildTwilioConnectActionUrl,
+  buildTwilioMediaStreamUrl,
+  buildTwilioRelayUrl,
+  buildTwilioStatusWebhookUrl,
+  buildTwilioVoiceWebhookUrl,
+  normalizePublicBaseUrl,
+} from "@vellumai/service-contracts/twilio-ingress";
+
 import { getIngressPublicBaseUrl } from "../config/env.js";
 
 export interface IngressConfig {
-  ingress?: { enabled?: boolean; publicBaseUrl?: string };
+  ingress?: {
+    enabled?: boolean;
+    publicBaseUrl?: string;
+  };
 }
 
-/**
- * Trim whitespace and strip trailing slashes from a URL string.
- */
-function normalizeUrl(url: string): string {
-  return url.trim().replace(/\/+$/, "");
+function assertPublicIngressEnabled(config: IngressConfig): void {
+  if (config.ingress?.enabled === false) {
+    throw new Error(
+      "Public ingress is disabled. Ask the assistant to enable it, or update it from the Settings page.",
+    );
+  }
 }
 
 /**
@@ -51,23 +64,15 @@ function normalizeUrl(url: string): string {
  * Throws if no source provides a non-empty value or if ingress is disabled.
  */
 export function getPublicBaseUrl(config: IngressConfig): string {
-  if (config.ingress?.enabled === false) {
-    throw new Error(
-      "Public ingress is disabled. Ask the assistant to enable it, or update it from the Settings page.",
-    );
-  }
+  assertPublicIngressEnabled(config);
 
   const ingressValue = config.ingress?.publicBaseUrl;
-  if (ingressValue) {
-    const normalized = normalizeUrl(ingressValue);
-    if (normalized) return normalized;
-  }
+  const normalizedIngressValue = normalizePublicBaseUrl(ingressValue);
+  if (normalizedIngressValue) return normalizedIngressValue;
 
   const ingressEnvValue = getIngressPublicBaseUrl();
-  if (ingressEnvValue) {
-    const normalized = normalizeUrl(ingressEnvValue);
-    if (normalized) return normalized;
-  }
+  const normalizedIngressEnvValue = normalizePublicBaseUrl(ingressEnvValue);
+  if (normalizedIngressEnvValue) return normalizedIngressEnvValue;
 
   throw new Error(
     "No public base URL configured. Set ingress.publicBaseUrl in config.",
@@ -87,27 +92,24 @@ export function getTwilioVoiceWebhookUrl(
   config: IngressConfig,
   callSessionId?: string,
 ): string {
-  const base = getPublicBaseUrl(config);
-  if (callSessionId) {
-    return `${base}/webhooks/twilio/voice?callSessionId=${callSessionId}`;
-  }
-  return `${base}/webhooks/twilio/voice`;
+  return buildTwilioVoiceWebhookUrl(
+    getPublicBaseUrl(config),
+    callSessionId,
+  );
 }
 
 /**
  * Build the Twilio status callback URL.
  */
 export function getTwilioStatusCallbackUrl(config: IngressConfig): string {
-  const base = getPublicBaseUrl(config);
-  return `${base}/webhooks/twilio/status`;
+  return buildTwilioStatusWebhookUrl(getPublicBaseUrl(config));
 }
 
 /**
  * Build the Twilio connect-action callback URL.
  */
 export function getTwilioConnectActionUrl(config: IngressConfig): string {
-  const base = getPublicBaseUrl(config);
-  return `${base}/webhooks/twilio/connect-action`;
+  return buildTwilioConnectActionUrl(getPublicBaseUrl(config));
 }
 
 /**
@@ -115,9 +117,7 @@ export function getTwilioConnectActionUrl(config: IngressConfig): string {
  * Converts http:// → ws:// and https:// → wss://.
  */
 export function getTwilioRelayUrl(config: IngressConfig): string {
-  const base = getPublicBaseUrl(config);
-  const wsBase = base.replace(/^http(s?)/, "ws$1");
-  return `${wsBase}/webhooks/twilio/relay`;
+  return buildTwilioRelayUrl(getPublicBaseUrl(config));
 }
 
 /**
@@ -127,9 +127,7 @@ export function getTwilioRelayUrl(config: IngressConfig): string {
  * Converts http:// → ws:// and https:// → wss://.
  */
 export function getTwilioMediaStreamUrl(config: IngressConfig): string {
-  const base = getPublicBaseUrl(config);
-  const wsBase = base.replace(/^http(s?)/, "ws$1");
-  return `${wsBase}/webhooks/twilio/media-stream`;
+  return buildTwilioMediaStreamUrl(getPublicBaseUrl(config));
 }
 
 /**

package/src/ipc/__tests__/clients-list-ipc.test.ts

@@ -0,0 +1,169 @@
+/**
+ * End-to-end test for `assistant clients list` over IPC.
+ *
+ * Regression test for the gap where the same-user filter on
+ * `GET /v1/clients` (which reads `headers["x-vellum-actor-principal-id"]`)
+ * silently returned an empty list over IPC because the IPC adapter did
+ * not inject the synthetic actor-principal header that the HTTP adapter
+ * populates from the verified `AuthContext`.
+ *
+ * Asserts that in non-dev-bypass mode (`isHttpAuthDisabled() === false`),
+ * the CLI sees same-user clients via the IPC path because the IPC server
+ * fills in the header from the local guardian principal.
+ */
+
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  test,
+} from "bun:test";
+
+import { runAssistantCommandFull } from "../../cli/__tests__/run-assistant-command.js";
+import { AssistantIpcServer } from "../assistant-server.js";
+
+// ── Module mocks (must be set up before importing the route) ──────────────
+
+let fakeHttpAuthDisabled = false;
+let fakeLocalPrincipalId: string | undefined = "guardian-local";
+
+mock.module("../../config/env.js", () => ({
+  isHttpAuthDisabled: () => fakeHttpAuthDisabled,
+  hasUngatedHttpAuthDisabled: () => false,
+}));
+
+mock.module("../../runtime/local-actor-identity.js", () => ({
+  findLocalGuardianPrincipalId: () => fakeLocalPrincipalId,
+}));
+
+// ── Real imports (after mocks) ────────────────────────────────────────────
+
+import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
+
+// ── Fixtures ──────────────────────────────────────────────────────────────
+
+let server: AssistantIpcServer | null = null;
+
+function registerClient(args: {
+  clientId: string;
+  actorPrincipalId?: string;
+}): void {
+  assistantEventHub.subscribe({
+    type: "client",
+    clientId: args.clientId,
+    interfaceId: "macos",
+    capabilities: ["host_bash", "host_file", "host_cu"],
+    actorPrincipalId: args.actorPrincipalId,
+    callback: () => {},
+  });
+}
+
+function clearHub(): void {
+  const ids = assistantEventHub.listClients().map((c) => c.clientId);
+  for (const id of ids) {
+    assistantEventHub.disposeClient(id);
+  }
+}
+
+async function startServer(): Promise<void> {
+  server = new AssistantIpcServer();
+  await server.start();
+  // Allow the listener to be ready before the CLI tries to connect.
+  await new Promise((resolve) => setTimeout(resolve, 50));
+}
+
+beforeEach(() => {
+  fakeHttpAuthDisabled = false;
+  fakeLocalPrincipalId = "guardian-local";
+  clearHub();
+});
+
+afterEach(() => {
+  server?.stop();
+  server = null;
+});
+
+afterAll(() => {
+  mock.restore();
+});
+
+// ── Tests ────────────────────────────────────────────────────────────────
+
+describe("assistant clients list over IPC — same-user filter", () => {
+  test("returns same-user clients in non-dev-bypass mode", async () => {
+    registerClient({
+      clientId: "client-self-1",
+      actorPrincipalId: "guardian-local",
+    });
+    registerClient({
+      clientId: "client-self-2",
+      actorPrincipalId: "guardian-local",
+    });
+    registerClient({
+      clientId: "client-other",
+      actorPrincipalId: "other-user",
+    });
+
+    await startServer();
+
+    const { stdout } = await runAssistantCommandFull(
+      "clients",
+      "list",
+      "--json",
+    );
+
+    const parsed = JSON.parse(stdout.trim()) as {
+      clients: Array<{ clientId: string }>;
+    };
+    const ids = parsed.clients.map((c) => c.clientId).sort();
+    expect(ids).toEqual(["client-self-1", "client-self-2"]);
+  });
+
+  test("returns empty when no local guardian principal is bound (fail-closed)", async () => {
+    fakeLocalPrincipalId = undefined;
+    registerClient({
+      clientId: "client-self",
+      actorPrincipalId: "guardian-local",
+    });
+
+    await startServer();
+
+    const { stdout } = await runAssistantCommandFull(
+      "clients",
+      "list",
+      "--json",
+    );
+    const parsed = JSON.parse(stdout.trim()) as {
+      clients: Array<{ clientId: string }>;
+    };
+    expect(parsed.clients).toEqual([]);
+  });
+
+  test("dev-bypass mode returns all clients regardless of principal", async () => {
+    fakeHttpAuthDisabled = true;
+    registerClient({
+      clientId: "client-self",
+      actorPrincipalId: "guardian-local",
+    });
+    registerClient({
+      clientId: "client-other",
+      actorPrincipalId: "other-user",
+    });
+
+    await startServer();
+
+    const { stdout } = await runAssistantCommandFull(
+      "clients",
+      "list",
+      "--json",
+    );
+    const parsed = JSON.parse(stdout.trim()) as {
+      clients: Array<{ clientId: string }>;
+    };
+    const ids = parsed.clients.map((c) => c.clientId).sort();
+    expect(ids).toEqual(["client-other", "client-self"]);
+  });
+});

package/src/ipc/__tests__/route-error-envelope.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Unit tests for the IPC error envelope built from `RouteError` instances.
+ *
+ * Asserts that `AssistantIpcServer.buildErrorResponse` forwards the full
+ * `RouteError` shape — including the `details` field — into the IPC response
+ * envelope so IPC clients (e.g. gateway→daemon) receive the same structured
+ * payload as HTTP clients (e.g. `version_incompatible` migration imports).
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+  RouteError,
+  UnprocessableEntityError,
+} from "../../runtime/routes/errors.js";
+import { AssistantIpcServer, type IpcResponse } from "../assistant-server.js";
+
+/**
+ * `buildErrorResponse` is private; access it through an interface cast so the
+ * test exercises the actual production code path without exporting a
+ * test-only API on the server class.
+ */
+type PrivateApi = {
+  buildErrorResponse(id: string, err: unknown): IpcResponse;
+};
+
+function buildErrorResponse(err: unknown): IpcResponse {
+  const server = new AssistantIpcServer() as unknown as PrivateApi;
+  return server.buildErrorResponse("req-1", err);
+}
+
+describe("AssistantIpcServer error envelope", () => {
+  test("forwards RouteError message, statusCode, and code", () => {
+    const err = new RouteError("boom", "BOOM", 418);
+    const response = buildErrorResponse(err);
+
+    expect(response.id).toBe("req-1");
+    expect(response.error).toBe("boom");
+    expect(response.statusCode).toBe(418);
+    expect(response.errorCode).toBe("BOOM");
+    expect(response.errorDetails).toBeUndefined();
+  });
+
+  test("forwards RouteError.details into errorDetails when present", () => {
+    const details = {
+      reason: "version_incompatible" as const,
+      bundle_compat: { engineMin: "0.7.0" },
+      runtime_version: "0.6.0",
+    };
+    const err = new UnprocessableEntityError(
+      "incompatible bundle version",
+      details,
+    );
+
+    const response = buildErrorResponse(err);
+
+    expect(response.errorCode).toBe("UNPROCESSABLE_ENTITY");
+    expect(response.statusCode).toBe(422);
+    expect(response.errorDetails).toEqual(details);
+  });
+
+  test("omits errorDetails when RouteError has no details", () => {
+    const err = new UnprocessableEntityError("plain validation failure");
+
+    const response = buildErrorResponse(err);
+
+    expect(response.errorCode).toBe("UNPROCESSABLE_ENTITY");
+    // `errorDetails` must be omitted entirely (not `undefined` value) so the
+    // serialized JSON envelope stays minimal.
+    expect("errorDetails" in response).toBe(false);
+  });
+
+  test("non-RouteError errors are stringified into `error`", () => {
+    const response = buildErrorResponse(new Error("raw"));
+
+    expect(response.error).toBe("Error: raw");
+    expect(response.errorCode).toBeUndefined();
+    expect(response.errorDetails).toBeUndefined();
+  });
+});

package/src/ipc/assistant-server.ts

@@ -32,9 +32,13 @@ import { existsSync, mkdirSync, unlinkSync } from "node:fs";
 import { createServer, type Server, type Socket } from "node:net";
 import { dirname } from "node:path";
 
+import { findLocalGuardianPrincipalId } from "../runtime/local-actor-identity.js";
 import { RouteError } from "../runtime/routes/errors.js";
 import { ROUTES } from "../runtime/routes/index.js";
-import type { RouteDefinition } from "../runtime/routes/types.js";
+import type {
+  RouteDefinition,
+  RouteHandlerArgs,
+} from "../runtime/routes/types.js";
 import { getLogger } from "../util/logger.js";
 import {
   type IpcEnvelope,
@@ -70,6 +74,14 @@ export type IpcResponse = {
   statusCode?: number;
   /** Machine-readable error code (e.g. "NOT_FOUND") for RouteError instances. */
   errorCode?: string;
+  /**
+   * Structured error payload mirroring `RouteError.details` — present only
+   * when the originating `RouteError` carries a `details` field (e.g.
+   * `version_incompatible` migration imports). Mirrors the HTTP adapter's
+   * `error.details` envelope so IPC clients can recover the same
+   * machine-readable context as HTTP clients.
+   */
+  errorDetails?: unknown;
   headers?: Record<string, string>;
 };
 
@@ -136,6 +148,7 @@ export class AssistantIpcServer {
     }
 
     // ⚠️  TEMPORARY — gateway→assistant DB proxy (see ipc/routes/db-proxy.ts).
+    // This is the ONLY route defined directly here; all other routes go in ROUTES.
     // Remove once contacts/guardian-binding logic is fully migrated to the
     // gateway's own database.
     this.methods.set("db_proxy", (params) =>
@@ -247,7 +260,8 @@ export class AssistantIpcServer {
     void binary;
 
     try {
-      const result = handler(req.params ?? {});
+      const handlerArgs = injectLocalActorHeader(req.params);
+      const result = handler(handlerArgs);
 
       if (result instanceof Promise) {
         result
@@ -273,12 +287,16 @@ export class AssistantIpcServer {
 
   private buildErrorResponse(id: string, err: unknown): IpcResponse {
     if (err instanceof RouteError) {
-      return {
+      const response: IpcResponse = {
         id,
         error: err.message,
         statusCode: err.statusCode,
         errorCode: err.code,
       };
+      if (err.details !== undefined) {
+        response.errorDetails = err.details;
+      }
+      return response;
     }
     return { id, error: String(err) };
   }
@@ -441,3 +459,52 @@ export class AssistantIpcServer {
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
+
+/**
+ * Inject a synthetic `x-vellum-actor-principal-id` header from the local
+ * guardian principal when the caller hasn't already provided one.
+ *
+ * Local IPC is intra-process and owned by the same user as the daemon, so
+ * routes that consume `headers["x-vellum-actor-principal-id"]` (e.g. the
+ * same-user filter on `GET /v1/clients`) need an actor identity to function
+ * over IPC. The HTTP adapter does this from the verified `AuthContext`
+ * (`http-adapter.ts`); this helper mirrors that convention for IPC.
+ *
+ * Existing headers from the caller (e.g. the gateway's IPC runtime proxy,
+ * which forwards real `x-vellum-*` headers from the authenticated HTTP
+ * request) are preserved — we only fill in the gap for direct CLI/local
+ * IPC callers.
+ */
+function injectLocalActorHeader(
+  params: Record<string, unknown> | undefined,
+): RouteHandlerArgs {
+  const args = (params ?? {}) as RouteHandlerArgs;
+  const existingHeaders = args.headers;
+  if (existingHeaders?.["x-vellum-actor-principal-id"]) {
+    return args;
+  }
+
+  // Defensive: the guardian lookup queries the contacts table, which may
+  // not yet exist on a very early boot path or in test fixtures that don't
+  // initialize the DB. A failure here must not block IPC dispatch — routes
+  // that require the header will fail-closed on their own.
+  let localActor: string | undefined;
+  try {
+    localActor = findLocalGuardianPrincipalId();
+  } catch (err) {
+    log.debug(
+      { err },
+      "failed to resolve local actor principal for IPC header injection",
+    );
+    return args;
+  }
+  if (!localActor) return args;
+
+  return {
+    ...args,
+    headers: {
+      ...existingHeaders,
+      "x-vellum-actor-principal-id": localActor,
+    },
+  };
+}

package/src/ipc/cli-client.ts

@@ -30,6 +30,16 @@ type IpcResponse = {
   id: string;
   result?: unknown;
   error?: string;
+  /** HTTP-style status code mirrored from `RouteError.statusCode`. */
+  statusCode?: number;
+  /** Machine-readable error code (e.g. "UNPROCESSABLE_ENTITY"). */
+  errorCode?: string;
+  /**
+   * Structured error payload mirroring `RouteError.details` — present only
+   * when the originating error carried a `details` field. Mirrors the HTTP
+   * adapter's `error.details` envelope.
+   */
+  errorDetails?: unknown;
 };
 
 // ---------------------------------------------------------------------------
@@ -43,6 +53,15 @@ export interface CliIpcCallResult<T = unknown> {
   ok: boolean;
   result?: T;
   error?: string;
+  /** HTTP-style status code surfaced from a daemon-side `RouteError`. */
+  statusCode?: number;
+  /** Machine-readable error code (e.g. "UNPROCESSABLE_ENTITY"). */
+  errorCode?: string;
+  /**
+   * Structured error payload mirroring `RouteError.details` — present only
+   * when the originating daemon-side error carried a `details` field.
+   */
+  errorDetails?: unknown;
 }
 
 /**
@@ -115,7 +134,19 @@ export async function cliIpcCall<T = unknown>(
             const msg = JSON.parse(line) as IpcResponse;
             if (msg.id === reqId) {
               if (msg.error) {
-                finish({ ok: false, error: msg.error });
+                finish({
+                  ok: false,
+                  error: msg.error,
+                  ...(msg.statusCode !== undefined && {
+                    statusCode: msg.statusCode,
+                  }),
+                  ...(msg.errorCode !== undefined && {
+                    errorCode: msg.errorCode,
+                  }),
+                  ...(msg.errorDetails !== undefined && {
+                    errorDetails: msg.errorDetails,
+                  }),
+                });
               } else {
                 finish({ ok: true, result: msg.result as T });
               }

package/src/ipc/gateway-client.ts

@@ -38,9 +38,10 @@ const log = getLogger("gateway-ipc-client");
 export async function ipcCall(
   method: string,
   params?: Record<string, unknown>,
+  timeoutMs?: number,
 ): Promise<unknown> {
   const socketPath = getGatewaySocketPath();
-  return packageIpcCall(socketPath, method, params, log);
+  return packageIpcCall(socketPath, method, params, log, timeoutMs);
 }
 
 // ---------------------------------------------------------------------------
@@ -90,9 +91,15 @@ export function resetPersistentClient(): void {
 /**
  * Fetch all merged feature flags from the gateway via IPC.
  * Returns an empty record on any failure.
+ *
+ * @param timeoutMs - Optional timeout override forwarded to the IPC
+ *   transport. Pass a small value (e.g. 200) for CLI startup paths where
+ *   a slow/absent gateway should fail fast.
  */
-export async function ipcGetFeatureFlags(): Promise<Record<string, boolean>> {
-  const result = await ipcCall("get_feature_flags");
+export async function ipcGetFeatureFlags(
+  timeoutMs?: number,
+): Promise<Record<string, boolean>> {
+  const result = await ipcCall("get_feature_flags", undefined, timeoutMs);
   if (result && typeof result === "object" && !Array.isArray(result)) {
     const filtered: Record<string, boolean> = {};
     for (const [k, v] of Object.entries(result as Record<string, unknown>)) {
@@ -103,6 +110,33 @@ export async function ipcGetFeatureFlags(): Promise<Record<string, boolean>> {
   return {};
 }
 
+// ---------------------------------------------------------------------------
+// Velay tunnel status
+// ---------------------------------------------------------------------------
+
+export interface VelayTunnelStatus {
+  connected: boolean;
+  publicUrl: string | null;
+}
+
+/**
+ * Fetch the current Velay tunnel status from the gateway via IPC.
+ * Returns `null` when the gateway is unreachable or returns an unexpected
+ * response — callers should treat `null` as "gateway not running".
+ */
+export async function ipcGetVelayStatus(): Promise<VelayTunnelStatus | null> {
+  const result = await ipcCall("get_velay_status");
+  if (!result || typeof result !== "object" || Array.isArray(result)) {
+    return null;
+  }
+  const obj = result as Record<string, unknown>;
+  if (typeof obj.connected !== "boolean") return null;
+  return {
+    connected: obj.connected,
+    publicUrl: typeof obj.publicUrl === "string" ? obj.publicUrl : null,
+  };
+}
+
 /**
  * Classify risk for a tool invocation via the gateway's persistent IPC
  * connection.

package/src/live-voice/live-voice-archive.ts

@@ -17,7 +17,7 @@ const LIVE_VOICE_AUDIO_SOURCE = "live-voice";
 
 export type LiveVoiceAudioArchiveRole = "user" | "assistant";
 
-export type LiveVoiceAudioSource =
+type LiveVoiceAudioSource =
   | {
       type: "base64";
       dataBase64: string;
@@ -28,7 +28,7 @@ export type LiveVoiceAudioSource =
       sizeBytes?: number;
     };
 
-export interface ArchiveLiveVoiceAudioInput {
+interface ArchiveLiveVoiceAudioInput {
   messageId: string;
   sessionId: string;
   turnId: string;
@@ -55,7 +55,7 @@ export interface LiveVoiceAudioArtifactMetadata {
   archivedAt: number;
 }
 
-export type LiveVoiceAudioArchiveWarningCode =
+type LiveVoiceAudioArchiveWarningCode =
   | "archive_failed"
   | "attachment_not_found"
   | "invalid_audio_source"
@@ -591,7 +591,7 @@ type LinkLiveVoiceRolelessAudioInput = Omit<
   messageId?: string | null;
 };
 
-export interface LinkLiveVoiceAudioArtifactInput {
+interface LinkLiveVoiceAudioArtifactInput {
   messageId?: string | null;
   artifact: LiveVoiceAudioArtifactMetadata;
   position?: number;