@vellumai/vellum-gateway 0.7.0 → 0.7.2

package/src/ipc/assistant-client.ts

@@ -324,6 +324,11 @@ export interface SuggestTrustRuleRequest {
   directoryScopeOptions?: DirectoryScopeOption[];
   currentThreshold: string; // "low" | "medium" | "high"
   intent: "auto_approve" | "escalate";
+  existingRule?: {
+    id: string;
+    pattern: string;
+    risk: string;
+  };
 }
 
 export interface SuggestTrustRuleResponse {
@@ -343,10 +348,9 @@ export interface SuggestTrustRuleResponse {
 export async function ipcSuggestTrustRule(
   params: SuggestTrustRuleRequest,
 ): Promise<SuggestTrustRuleResponse> {
-  const result = await ipcCallAssistant(
-    "suggest_trust_rule",
-    { body: params } as unknown as Record<string, unknown>,
-  );
+  const result = await ipcCallAssistant("suggest_trust_rule", {
+    body: params,
+  } as unknown as Record<string, unknown>);
   if (!result || typeof result !== "object" || Array.isArray(result)) {
     throw new Error("ipcSuggestTrustRule: unexpected response shape");
   }

package/src/ipc/contact-handlers.ts

@@ -1,15 +1,23 @@
 /**
- * IPC route definitions for contact reads.
+ * IPC route definitions for contact reads and writes.
  *
- * Exposes gateway-owned contact data (auth/authz) to the assistant
- * daemon over the IPC socket. All methods are read-only.
+ * Read methods expose gateway-owned contact data to the assistant daemon.
+ * The `create_contact` write method upserts a contact+channel via the
+ * assistant DB proxy (raw SQL), so the gateway owns the write path.
  */
 
 import { z } from "zod";
 
+import {
+  assistantDbQuery,
+  assistantDbRun,
+} from "../db/assistant-db-proxy.js";
 import { ContactStore } from "../db/contact-store.js";
+import { getLogger } from "../logger.js";
 import type { IpcRoute } from "./server.js";
 
+const log = getLogger("contact-handlers");
+
 let store: ContactStore | null = null;
 
 function getStore(): ContactStore {
@@ -19,6 +27,13 @@ function getStore(): ContactStore {
   return store;
 }
 
+const CreateContactParamsSchema = z.object({
+  channelType: z.string().min(1),
+  address: z.string().min(1),
+  role: z.enum(["guardian", "trusted-contact", "unknown"]).optional(),
+  displayName: z.string().optional(),
+});
+
 const GetContactParamsSchema = z.object({
   contactId: z.string(),
 });
@@ -64,4 +79,74 @@ export const contactRoutes: IpcRoute[] = [
       return getStore().getChannelsForContact(contactId);
     },
   },
+  {
+    method: "create_contact",
+    schema: CreateContactParamsSchema,
+    handler: async (params?: Record<string, unknown>) => {
+      const { channelType, address, role, displayName } =
+        CreateContactParamsSchema.parse(params);
+
+      const normalizedAddress = address.toLowerCase().trim();
+      const effectiveDisplayName = displayName ?? normalizedAddress;
+      // Map prompt roles to valid ContactRole values ("guardian" | "contact").
+      const effectiveRole: string =
+        role === "guardian" ? "guardian" : "contact";
+      const now = Date.now();
+
+      // Check if a channel with this (type, address) already exists.
+      const existing = await assistantDbQuery<{
+        channelId: string;
+        contactId: string;
+      }>(
+        `SELECT cc.id AS channelId, cc.contact_id AS contactId
+         FROM contact_channels cc
+         WHERE cc.type = ? AND cc.address = ?
+         LIMIT 1`,
+        [channelType, normalizedAddress],
+      );
+
+      if (existing.length > 0) {
+        const { channelId, contactId } = existing[0];
+        log.info(
+          { channelType, address: normalizedAddress, contactId, channelId },
+          "create_contact: channel already exists, returning existing record",
+        );
+        return { contactId, channelId };
+      }
+
+      // Create a new contact + channel.
+      // Two separate INSERTs — use a compensating DELETE on channel failure.
+      const contactId = crypto.randomUUID();
+      const channelId = crypto.randomUUID();
+
+      await assistantDbRun(
+        `INSERT INTO contacts (id, display_name, role, contact_type, created_at, updated_at)
+         VALUES (?, ?, ?, 'human', ?, ?)`,
+        [contactId, effectiveDisplayName, effectiveRole, now, now],
+      );
+
+      try {
+        await assistantDbRun(
+          `INSERT INTO contact_channels (id, contact_id, type, address, is_primary, status, policy, interaction_count, created_at, updated_at)
+           VALUES (?, ?, ?, ?, 1, 'unverified', 'allow', 0, ?, ?)`,
+          [channelId, contactId, channelType, normalizedAddress, now, now],
+        );
+      } catch (channelErr) {
+        // Compensating delete — remove the orphaned contact row.
+        log.error(
+          { channelErr, contactId, channelType, address: normalizedAddress },
+          "create_contact: channel INSERT failed, rolling back contact row",
+        );
+        await assistantDbRun("DELETE FROM contacts WHERE id = ?", [contactId]);
+        throw channelErr;
+      }
+
+      log.info(
+        { channelType, address: normalizedAddress, contactId, channelId, role: effectiveRole },
+        "create_contact: created new contact + channel",
+      );
+
+      return { contactId, channelId };
+    },
+  },
 ];

package/src/ipc/threshold-handlers.ts

@@ -18,6 +18,7 @@ import type { IpcRoute } from "./server.js";
 const GLOBAL_DEFAULTS = {
   interactive: "medium",
   autonomous: "low",
+  headless: "none",
 };
 
 const GetConversationThresholdSchema = z.object({
@@ -45,6 +46,7 @@ export const thresholdRoutes: IpcRoute[] = [
       return {
         interactive: row.interactive,
         autonomous: row.autonomous,
+        headless: row.headless,
       };
     },
   },

package/src/post-assistant-ready.ts

@@ -8,7 +8,9 @@
  * assistant DB doesn't exist yet.
  *
  * This module polls the assistant IPC health route and, once the assistant
- * is ready, runs all deferred startup tasks.
+ * is ready, runs data migrations and other deferred tasks. It is awaited
+ * during startup — the HTTP server does not start until this completes,
+ * preventing auth traffic from racing with data migrations.
  */
 
 import type { Database } from "bun:sqlite";
@@ -28,7 +30,7 @@ function getRawDb(drizzleDb: GatewayDb): Database {
   return (drizzleDb as unknown as { $client: Database }).$client;
 }
 
-async function waitForAssistant(): Promise<boolean> {
+export async function waitForAssistant(): Promise<boolean> {
   const deadline = Date.now() + MAX_WAIT_MS;
 
   while (Date.now() < deadline) {
@@ -50,7 +52,7 @@ async function waitForAssistant(): Promise<boolean> {
 
 /**
  * Wait for the assistant runtime to become healthy, then run deferred
- * startup tasks. Fire-and-forget from the main startup path.
+ * startup tasks. Awaited at startup — blocks Bun.serve().
  */
 export async function runPostAssistantReady(): Promise<void> {
   const ready = await waitForAssistant();

package/src/risk/bash-risk-classifier.test.ts

@@ -765,13 +765,13 @@ describe("unknown commands", () => {
     expect(result.matchType).toBe("registry");
   });
 
-  test("unknown command with --help → low risk", async () => {
+  test("unknown command with --help → unknown risk", async () => {
     const result = await classifier.classify({
       command: "mycustomtool --help",
       toolName: "bash",
     });
-    expect(result.riskLevel).toBe("low");
-    expect(result.matchType).toBe("registry");
+    expect(result.riskLevel).toBe("unknown");
+    expect(result.matchType).toBe("unknown");
   });
 
   test("--help after -- is positional, not help mode", async () => {
@@ -781,6 +781,38 @@ describe("unknown commands", () => {
     });
     expect(result.riskLevel).toBe("high");
   });
+
+  test("value-taking flags do not trigger help shortcut", async () => {
+    const result = await classifier.classify({
+      command: "tar -f --help /etc/passwd",
+      toolName: "bash",
+    });
+    expect(result.riskLevel).toBe("medium");
+  });
+
+  test("commands without arg schema do not use help shortcut", async () => {
+    const result = await classifier.classify({
+      command: "bash --rcfile --help -c 'rm -rf /'",
+      toolName: "bash",
+    });
+    expect(result.riskLevel).toBe("high");
+  });
+
+  test("bundled short flags with value flag do not trigger help shortcut", async () => {
+    const result = await classifier.classify({
+      command: "tar -xf --help /etc/passwd",
+      toolName: "bash",
+    });
+    expect(result.riskLevel).toBe("medium");
+  });
+
+  test("known command without argSchema + --help uses base risk", async () => {
+    const result = await classifier.classify({
+      command: "kill --help",
+      toolName: "bash",
+    });
+    expect(result.riskLevel).toBe("high");
+  });
 });
 
 // ── Variable expansion escalation ────────────────────────────────────────────
@@ -923,30 +955,6 @@ describe("assistant subcommand classification", () => {
     expect(result.riskLevel).toBe("high");
   });
 
-  test("assistant trust remove → high", async () => {
-    const result = await classifier.classify({
-      command: "assistant trust remove",
-      toolName: "bash",
-    });
-    expect(result.riskLevel).toBe("high");
-  });
-
-  test("assistant trust add → high", async () => {
-    const result = await classifier.classify({
-      command: "assistant trust add",
-      toolName: "bash",
-    });
-    expect(result.riskLevel).toBe("high");
-  });
-
-  test("assistant trust update → high", async () => {
-    const result = await classifier.classify({
-      command: "assistant trust update",
-      toolName: "bash",
-    });
-    expect(result.riskLevel).toBe("high");
-  });
-
   test("assistant config set → low", async () => {
     const result = await classifier.classify({
       command: "assistant config set key value",

package/src/risk/bash-risk-classifier.ts

@@ -189,14 +189,48 @@ const RM_BENIGN_FLAGS = new Set([
 ]);
 
 /**
- * Returns true when the command arguments include a top-level `--help` flag.
+ * Returns true when args contain a top-level help option that is not consumed
+ * as a value by another flag.
  *
- * This intentionally ignores any `--help` token that appears after `--`
- * because those are positional arguments, not options.
+ * This intentionally ignores:
+ * - any `--help` token that appears after `--` (positional mode), and
+ * - any `--help` token consumed as the value of a known value-taking flag.
+ *
+ * Help-mode shortcuts are only enabled for commands with an arg schema.
  */
-function hasHelpFlag(args: string[]): boolean {
-  for (const arg of args) {
+function hasStandaloneHelpFlag(args: string[], schema?: ArgSchema): boolean {
+  if (!schema) return false;
+
+  const valueFlags = new Set(schema.valueFlags ?? []);
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
     if (arg === "--") return false;
+
+    // Value-taking flags consume the next token (if present), so that token
+    // must not be interpreted as a standalone top-level option.
+    if (valueFlags.has(arg)) {
+      if (i + 1 < args.length) i++;
+      continue;
+    }
+
+    // Short-flag bundles: -xf where -f is a value flag.  POSIX convention
+    // places the value-consuming flag last in a bundle, so check the final
+    // character.  If it matches a known short value flag, the next token is
+    // its value and must be skipped.
+    if (arg.startsWith("-") && !arg.startsWith("--") && arg.length > 2) {
+      const lastChar = arg[arg.length - 1];
+      if (lastChar && valueFlags.has(`-${lastChar}`)) {
+        if (i + 1 < args.length) i++;
+        continue;
+      }
+    }
+
+    if (arg.startsWith("-") && arg.includes("=")) {
+      const eqIdx = arg.indexOf("=");
+      const flagPart = arg.slice(0, eqIdx);
+      if (valueFlags.has(flagPart)) continue;
+    }
+
     if (arg === "--help" || arg.startsWith("--help=")) return true;
   }
   return false;
@@ -280,14 +314,6 @@ export function classifySegment(
   }
 
   if (!spec) {
-    // Unknown command with --help is just viewing help → low risk
-    if (hasHelpFlag(segment.args)) {
-      return {
-        risk: "low",
-        reason: `${segment.program} help output`,
-        matchType: "registry",
-      };
-    }
     return {
       risk: "unknown",
       reason: `Unknown command: ${segment.program}`,
@@ -299,7 +325,11 @@ export function classifySegment(
   //     Commands WITH subcommands (e.g. `assistant`) skip this — their
   //     subcommand resolution may assign elevated risk that --help must
   //     not bypass.
-  if (!spec.subcommands && !spec.isWrapper && hasHelpFlag(segment.args)) {
+  if (
+    !spec.subcommands &&
+    !spec.isWrapper &&
+    hasStandaloneHelpFlag(segment.args, spec.argSchema)
+  ) {
     return {
       risk: "low",
       reason: `${segment.program} help output`,

package/src/risk/command-registry/commands/assistant.ts

@@ -73,6 +73,7 @@ const ASSISTANT_SUPPORTED_COMMAND_PATHS = [
   "channel-verification-sessions cancel",
   "channel-verification-sessions revoke",
   "clients",
+  "clients disconnect",
   "clients list",
   "completions",
   "config",
@@ -85,6 +86,7 @@ const ASSISTANT_SUPPORTED_COMMAND_PATHS = [
   "contacts list",
   "contacts get",
   "contacts merge",
+  "contacts prompt",
   "contacts upsert",
   "contacts channels",
   "contacts channels update-status",
@@ -108,6 +110,8 @@ const ASSISTANT_SUPPORTED_COMMAND_PATHS = [
   "credential-execution",
   "credential-execution grants",
   "credential-execution grants list",
+  "pending",
+  "pending list",
   "credential-execution grants revoke",
   "credential-execution audit",
   "credential-execution audit list",
@@ -118,6 +122,9 @@ const ASSISTANT_SUPPORTED_COMMAND_PATHS = [
   "credentials delete",
   "credentials inspect",
   "credentials reveal",
+  "gateway",
+  "gateway logs",
+  "gateway logs tail",
   "image-generation",
   "image-generation generate",
   "inference",
@@ -212,9 +219,6 @@ const ASSISTANT_SUPPORTED_COMMAND_PATHS = [
   "task queue run",
   "trust",
   "trust list",
-  "trust add",
-  "trust update",
-  "trust remove",
   "tts",
   "tts synthesize",
   "ui",
@@ -336,22 +340,6 @@ const riskOverrides: AssistantRiskOverride[] = [
     risk: "high",
     reason: "Deletes API key material",
   },
-  {
-    path: "trust add",
-    risk: "high",
-    reason: "Creates trust rule that affects auto-approve behavior",
-  },
-  {
-    path: "trust update",
-    risk: "high",
-    reason: "Modifies trust rule risk level or description",
-  },
-  {
-    path: "trust remove",
-    risk: "high",
-    reason: "Removes trust rule",
-  },
-
   // Destructive assistant-state operations
   {
     path: "backup restore",
@@ -390,6 +378,7 @@ const riskOverrides: AssistantRiskOverride[] = [
   { path: "channel-verification-sessions revoke", risk: "low" },
   { path: "config set", risk: "low" },
   { path: "contacts merge", risk: "medium" },
+  { path: "contacts prompt", risk: "medium" },
   { path: "contacts upsert", risk: "medium" },
   { path: "contacts channels update-status", risk: "medium" },
   { path: "contacts invites create", risk: "high" },

package/src/risk/command-registry.test.ts

@@ -474,18 +474,6 @@ describe("command-registry", () => {
       test("assistant trust (bare) is low risk", () => {
         expect(trustSpec.baseRisk).toBe("low");
       });
-
-      test("assistant trust remove is high risk", () => {
-        expect(trustSpec.subcommands!.remove.baseRisk).toBe("high");
-      });
-
-      test("assistant trust add is high risk", () => {
-        expect(trustSpec.subcommands!.add.baseRisk).toBe("high");
-      });
-
-      test("assistant trust update is high risk", () => {
-        expect(trustSpec.subcommands!.update.baseRisk).toBe("high");
-      });
     });
 
     // ── low-risk subcommands (no further subcommands) ────────────────────
@@ -545,9 +533,6 @@ describe("command-registry", () => {
         assistantSpec.subcommands!.trust.subcommands!,
       );
       expect(trustSubs).toContain("list");
-      expect(trustSubs).toContain("add");
-      expect(trustSubs).toContain("update");
-      expect(trustSubs).toContain("remove");
     });
 
     test("covers expanded top-level assistant command groups", () => {

package/src/risk/risk-classifier-parity.test.ts

@@ -51,7 +51,7 @@ const BASH_TEST_CASES: Array<[string, RiskLevel]> = [
   ["command -v rm", RiskLevel.Low],
   ["command -V sudo", RiskLevel.Low],
   ["rm --help", RiskLevel.Low],
-  ["mycustomtool --help", RiskLevel.Low],
+  ["mycustomtool --help", RiskLevel.Medium],
 
   // Medium risk
   ["git push origin main", RiskLevel.Medium],
@@ -70,8 +70,6 @@ const BASH_TEST_CASES: Array<[string, RiskLevel]> = [
   ["chgrp group file.txt", RiskLevel.High],
   ['eval "ls"', RiskLevel.High],
   ['bash -c "echo hi"', RiskLevel.High],
-  ["assistant trust add", RiskLevel.High],
-  ["assistant trust update", RiskLevel.High],
   ["sudo rm -rf /", RiskLevel.High],
   ["rm -rf /tmp/stuff", RiskLevel.High],
   ["rm -r directory", RiskLevel.High],

package/src/runtime/client.ts

@@ -2,8 +2,13 @@ import {
   buildUpstreamUrl,
   createTimeoutController,
 } from "@vellumai/assistant-client";
+import {
+  normalizePublicBaseUrl,
+  TWILIO_PUBLIC_BASE_WSS_PLACEHOLDER,
+} from "@vellumai/service-contracts/twilio-ingress";
 
 import type { ChannelId, InterfaceId } from "../channels/types.js";
+import type { ConfigFileCache } from "../config-file-cache.js";
 import {
   mintIngressToken,
   mintRelayToken,
@@ -494,14 +499,46 @@ export type TwilioForwardResponse = {
  */
 const TWILIO_RELAY_TOKEN_PLACEHOLDER = "__VELLUM_RELAY_TOKEN__";
 
+/**
+ * Resolve the public base URL as a WebSocket URL (`wss://…`).
+ *
+ * Sources (in priority order):
+ * 1. `VELAY_BASE_URL` — present on platform-hosted gateway sidecars.
+ *    When Velay is the tunnel provider, Twilio WebSocket connections
+ *    are routed through the Velay service URL.
+ * 2. `ingress.publicBaseUrl` from the config file — written by Velay
+ *    on tunnel registration, or set manually for self-hosted.
+ *
+ * Returns `undefined` when no source provides a value — the placeholder
+ * will remain in TwiML and Twilio will fail to connect, which is the
+ * correct behavior since without a public URL the assistant is unreachable.
+ */
+export function resolvePublicBaseWssUrl(
+  config: GatewayConfig,
+  configFile?: ConfigFileCache,
+  platformAssistantId?: string,
+): string | undefined {
+  if (config.velayBaseUrl && platformAssistantId) {
+    const withPath =
+      config.velayBaseUrl.replace(/\/+$/, "") + "/" + platformAssistantId;
+    const normalized = normalizePublicBaseUrl(withPath);
+    if (normalized) return normalized.replace(/^http(s?)/, "ws$1");
+  }
+  const raw = configFile?.getString("ingress", "publicBaseUrl");
+  const normalized = normalizePublicBaseUrl(raw);
+  if (!normalized) return undefined;
+  return normalized.replace(/^http(s?)/, "ws$1");
+}
+
 /**
  * Forward a validated Twilio voice webhook payload to the runtime.
  * The gateway sends the parsed form params as JSON; the runtime's internal
  * endpoint reconstructs what it needs.
  *
- * After receiving the TwiML response, the gateway replaces the relay token
- * placeholder with a freshly minted JWT so the daemon never needs the
- * signing key for voice webhook responses.
+ * After receiving the TwiML response, the gateway:
+ * 1. Replaces the relay token placeholder with a freshly minted JWT.
+ * 2. Replaces the public base URL placeholder with the real public
+ *    WebSocket URL so the assistant never needs `ingress.publicBaseUrl`.
  *
  * For inbound calls, `assistantId` is resolved by the gateway from the "To"
  * phone number and forwarded so the runtime knows which assistant to bootstrap.
@@ -510,6 +547,7 @@ export async function forwardTwilioVoiceWebhook(
   config: GatewayConfig,
   params: Record<string, string>,
   originalUrl: string,
+  publicBaseWssUrl?: string,
 ): Promise<TwilioForwardResponse> {
   cbBeforeRequest();
 
@@ -547,6 +585,23 @@ export async function forwardTwilioVoiceWebhook(
     body = body.replaceAll(TWILIO_RELAY_TOKEN_PLACEHOLDER, mintRelayToken());
   }
 
+  // Replace the public base URL placeholder with the real WebSocket URL.
+  // The assistant emits wss://__VELLUM_PUBLIC_BASE_URL__/… so it never
+  // needs ingress.publicBaseUrl — the gateway owns URL resolution.
+  if (body.includes(TWILIO_PUBLIC_BASE_WSS_PLACEHOLDER)) {
+    if (publicBaseWssUrl) {
+      body = body.replaceAll(
+        TWILIO_PUBLIC_BASE_WSS_PLACEHOLDER,
+        publicBaseWssUrl.replace(/\/+$/, ""),
+      );
+    } else {
+      log.error(
+        "TwiML contains public URL placeholder but no public base URL is configured. " +
+          "Twilio will fail to connect. Set VELAY_BASE_URL or ingress.publicBaseUrl.",
+      );
+    }
+  }
+
   if (response.status >= 500) cbOnFailure();
   else cbOnSuccess();
   return { status: response.status, body, headers };