@vellumai/vellum-gateway 0.7.2 → 0.8.0

package/ARCHITECTURE.md

@@ -280,10 +280,10 @@ Channel bindings follow a three-phase lifecycle:
 
 The public URL where the gateway is reachable is configured via:
 
-| Source                                           | Description                                                                                                                                                |
-| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ingress.publicBaseUrl` (workspace config)       | Canonical public ingress URL for Telegram webhooks, OAuth callbacks, email callbacks, generic JSON webhooks, and custom/ngrok tunnel based Twilio fallback |
-| `ingress.twilioPublicBaseUrl` (workspace config) | Twilio-specific public ingress URL written by Velay registration; used only by Twilio URL builders when present                                            |
+| Source                                              | Description                                                                                                                                             |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ingress.publicBaseUrl` (workspace config)          | Canonical public ingress URL for Telegram webhooks, OAuth callbacks, email callbacks, generic JSON webhooks, Twilio webhooks, and Twilio WebSocket URLs |
+| `ingress.publicBaseUrlManagedBy` (workspace config) | Ownership marker used when Velay published `ingress.publicBaseUrl`; lets the gateway clear stale Velay-managed URLs without disturbing manual URLs      |
 
 ### Tunnel-Agnostic Setup
 
@@ -296,9 +296,9 @@ The assistant runtime reads this URL via the centralized `public-ingress-urls.ts
 
 ### Velay Twilio Ingress
 
-Velay is a platform-managed tunnel for assistant-hosted HTTP and WebSocket traffic. It is intentionally additive to the tunnel-agnostic setup above: Velay registration does not overwrite `ingress.publicBaseUrl`, and operators can continue using ngrok or custom tunnels for non-Twilio webhooks.
+Velay is a platform-managed tunnel for assistant-hosted HTTP and WebSocket traffic. When it is active, Velay publishes the registered public assistant URL to `ingress.publicBaseUrl` and marks it with `ingress.publicBaseUrlManagedBy: "velay"`.
 
-When `VELAY_BASE_URL` is present in the gateway environment, the gateway starts `VelayTunnelClient`. The client registers with Velay over `GET /v1/register` using the assistant API key, then receives a `registered` frame containing a public assistant URL such as `https://velay.vellum.ai/<assistant-id>`. The gateway writes that URL to `ingress.twilioPublicBaseUrl` only. When the tunnel disconnects, it clears that same value if it still matches the URL the tunnel published, leaving `ingress.publicBaseUrl` intact.
+When `VELAY_BASE_URL` is present in the gateway environment, the gateway starts `VelayTunnelClient`. The client registers with Velay over `GET /v1/register` using the assistant API key, then receives a `registered` frame containing a public assistant URL such as `https://velay.vellum.ai/<assistant-id>`. The gateway writes that URL to `ingress.publicBaseUrl`. When the tunnel disconnects, it clears that value only if the Velay ownership marker is still present and the URL still matches what the tunnel published, leaving manual URLs intact.
 
 Velay forwards both HTTP request frames and WebSocket frames into the local gateway loopback listener:
 
@@ -310,16 +310,16 @@ Public Velay HTTPS/WSS URL
   → Existing gateway route handlers
 ```
 
-The HTTP bridge can carry normal JSON requests and health checks, so it is useful for local bridge smoke tests. The advertised URL split is Twilio-scoped in this phase, though: only Twilio URL generation prefers `ingress.twilioPublicBaseUrl`; Telegram webhook registration, OAuth redirects, email callbacks, and generic public URL builders continue to use `ingress.publicBaseUrl`.
+The HTTP bridge can carry normal JSON requests and health checks, so it is useful for local bridge smoke tests. Velay-managed `ingress.publicBaseUrl` changes are tagged with `publicBaseUrlManagedBy` so gateway side effects can skip unrelated webhook reconciliation while still refreshing Twilio phone-number webhooks.
 
 Local platform smoke-test flow:
 
 1. In `vellum-assistant-platform`, run `vel up velay`.
-2. Ensure vembda passes `VELAY_BASE_URL=http://host.docker.internal:8501` into assistant gateway containers.
+2. Ensure vembda passes the environment-appropriate `VELAY_BASE_URL` into assistant gateway containers.
 3. Re-hatch or restart the assistant so the gateway receives the new environment.
 4. Confirm gateway logs show `Velay tunnel connected` and `Velay tunnel registered`.
 5. Verify HTTP forwarding by requesting `${VELAY_PUBLIC_BASE_URL}/<assistant-id>/healthz` and `${VELAY_PUBLIC_BASE_URL}/<assistant-id>/schema`. When validating a JSON webhook route under active development, POST a small JSON body through the same Velay public URL and confirm it reaches the loopback gateway.
-6. Verify Twilio WebSocket forwarding with a synthetic local WebSocket client against `${VELAY_PUBLIC_BASE_URL}/<assistant-id>/webhooks/twilio/relay?callSessionId=...&token=...`, then with a real Twilio call after `VELAY_PUBLIC_BASE_URL` is backed by a public HTTPS/WSS tunnel.
+6. Verify Twilio WebSocket forwarding with a synthetic local WebSocket client against `${VELAY_PUBLIC_BASE_URL}/<assistant-id>/webhooks/twilio/relay?callSessionId=...&token=...`, then with a real Twilio call after the gateway has registered with Velay.
 
 ### URL Builders
 
@@ -328,10 +328,10 @@ All public-facing URLs are constructed by `assistant/src/inbound/public-ingress-
 | Function                       | URL Pattern                                                                                                                                                      |
 | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `getPublicBaseUrl()`           | Resolves the canonical base URL from `ingress.publicBaseUrl` in workspace config or module-level state (assistant-side; the gateway reads via `ConfigFileCache`) |
-| `getTwilioVoiceWebhookUrl()`   | `${twilioBase}/webhooks/twilio/voice?callSessionId=...`, where `twilioBase` is `ingress.twilioPublicBaseUrl` when present, otherwise `ingress.publicBaseUrl`     |
-| `getTwilioStatusCallbackUrl()` | `${twilioBase}/webhooks/twilio/status`, with the same Twilio-specific base resolution                                                                            |
-| `getTwilioConnectActionUrl()`  | `${twilioBase}/webhooks/twilio/connect-action`, with the same Twilio-specific base resolution                                                                    |
-| `getTwilioRelayUrl()`          | `ws(s)://.../webhooks/twilio/relay`, with the same Twilio-specific base resolution                                                                               |
+| `getTwilioVoiceWebhookUrl()`   | `${base}/webhooks/twilio/voice?callSessionId=...`, using `ingress.publicBaseUrl`                                                                                 |
+| `getTwilioStatusCallbackUrl()` | `${base}/webhooks/twilio/status`, using `ingress.publicBaseUrl`                                                                                                  |
+| `getTwilioConnectActionUrl()`  | `${base}/webhooks/twilio/connect-action`, using `ingress.publicBaseUrl`                                                                                          |
+| `getTwilioRelayUrl()`          | `ws(s)://.../webhooks/twilio/relay`, using `ingress.publicBaseUrl`                                                                                               |
 | `getOAuthCallbackUrl()`        | `${base}/webhooks/oauth/callback`                                                                                                                                |
 | `getTelegramWebhookUrl()`      | `${base}/webhooks/telegram`                                                                                                                                      |
 
@@ -1077,21 +1077,20 @@ In gateway-fronted deployments, the TwiML WebSocket URL (returned by the voice w
 
 Signature validation is **fail-closed**: if the Twilio auth token is not configured, all webhook requests are rejected with `403`. Missing or invalid `X-Twilio-Signature` headers are also rejected with `403`. Payload size is capped by `maxWebhookPayloadBytes` (checked via both `Content-Length` header and actual body size).
 
-**Webhook base URL resolution:** Public ingress URL construction is centralized in `public-ingress-urls.ts`, with a Twilio-specific override for Velay:
+**Webhook base URL resolution:** Public ingress URL construction is centralized in `public-ingress-urls.ts`:
 
-- Twilio voice/status/connect-action/relay/media-stream URLs use `ingress.twilioPublicBaseUrl` when present. This is the value published by Velay registration.
-- If `ingress.twilioPublicBaseUrl` is absent, Twilio falls back to `ingress.publicBaseUrl`.
-- Telegram webhooks, OAuth callbacks, email callbacks, and normal JSON webhook URLs use `ingress.publicBaseUrl`; Velay does not replace those advertised URLs in this phase.
+- Twilio voice/status/connect-action/relay/media-stream URLs use `ingress.publicBaseUrl`.
+- Velay registration publishes its public assistant URL to `ingress.publicBaseUrl` with `ingress.publicBaseUrlManagedBy: "velay"`.
+- Telegram webhooks, OAuth callbacks, email callbacks, and normal JSON webhook URLs also use `ingress.publicBaseUrl`; Velay-managed URL changes are tagged so unrelated reconciliation can be skipped when appropriate.
 - Module-level assistant state remains a fallback for legacy tunnel start/stop flows.
 
 All webhook paths (`/webhooks/twilio/voice`, `/webhooks/twilio/status`, `/webhooks/telegram`, `/webhooks/oauth/callback`, etc.) are appended automatically.
 
 For **inbound Twilio signature validation** at the gateway, URL reconstruction now supports multiple candidates in order:
 
-1. `ConfigFileCache.getString("ingress", "twilioPublicBaseUrl")` (if configured)
-2. `ConfigFileCache.getString("ingress", "publicBaseUrl")` (if configured)
-3. Forwarded public URL headers from the tunnel/proxy (`X-Forwarded-Proto` + `X-Forwarded-Host`/`X-Original-Host` fallbacks)
-4. Raw request URL (always included as the final fallback)
+1. `ConfigFileCache.getString("ingress", "publicBaseUrl")` (if configured)
+2. Forwarded public URL headers from the tunnel/proxy (`X-Forwarded-Proto` + `X-Forwarded-Host`/`X-Original-Host` fallbacks)
+3. Raw request URL (always included as the final fallback)
 
 This makes ingress URL updates smoother in local tunnel workflows because Twilio webhooks can continue validating immediately. For Telegram, the config file watcher detects ingress URL changes and triggers webhook reconciliation directly, so neither channel requires a gateway restart.
 

package/Dockerfile

@@ -11,6 +11,7 @@ COPY --from=bun /usr/local/bin/bun /usr/local/bin/bun
 # Copy shared packages needed by gateway's repo-local dependencies
 COPY packages/assistant-client ./packages/assistant-client
 COPY packages/ces-client ./packages/ces-client
+COPY packages/ipc-server-utils ./packages/ipc-server-utils
 COPY packages/service-contracts ./packages/service-contracts
 COPY packages/slack-text ./packages/slack-text
 COPY packages/twilio-client ./packages/twilio-client
@@ -56,4 +57,4 @@ EXPOSE 7830
 
 ENV GATEWAY_PORT=7830
 
-CMD ["bun", "run", "src/index.ts"]
+CMD ["bun", "--smol", "run", "src/index.ts"]

package/README.md

@@ -210,9 +210,9 @@ In local tunnel setups, updating `ingress.publicBaseUrl` in Settings is typicall
 
 The assistant runtime uses this URL to construct all webhook and OAuth callback URLs automatically.
 
-### Velay for Twilio Local Testing
+### Velay for Twilio Testing
 
-Velay is an additional managed ingress transport for Twilio calls. It does not replace ngrok or `ingress.publicBaseUrl`. In this phase, Velay registration writes only `ingress.twilioPublicBaseUrl`; Twilio URL builders prefer that value when it is present, while Telegram webhooks, OAuth callbacks, email callbacks, and normal JSON webhook URLs continue to use `ingress.publicBaseUrl`.
+Velay is a managed ingress transport for assistant-hosted HTTP and WebSocket traffic. When Velay registration succeeds, the gateway writes the registered public assistant URL to `ingress.publicBaseUrl` and marks it with `ingress.publicBaseUrlManagedBy: "velay"`. Twilio URL builders use that public base URL for voice, status, relay, and media-stream endpoints.
 
 Use Velay when testing Twilio voice webhooks or Twilio WebSocket upgrades through the platform-managed tunnel:
 
@@ -222,16 +222,16 @@ Use Velay when testing Twilio voice webhooks or Twilio WebSocket upgrades throug
    vel up velay
    ```
 
-2. Ensure vembda injects the Velay endpoint into assistant gateway containers:
+2. Ensure vembda injects the Velay endpoint into assistant gateway containers. For local Docker-hosted assistants, the gateway container must dial the Velay service running on the host:
 
    ```bash
    VELAY_BASE_URL=http://host.docker.internal:8501
    ```
 
-   The `host.docker.internal` host is important for Docker-hosted assistants because the gateway container must dial the Velay service running on the host.
+   Hosted environments should use their environment's deployed Velay URL instead.
 
 3. Re-hatch or restart the assistant so the gateway process receives `VELAY_BASE_URL`.
-4. Confirm the gateway logs include `Velay tunnel connected` followed by `Velay tunnel registered`. Registration publishes the returned Velay URL to `ingress.twilioPublicBaseUrl` without changing `ingress.publicBaseUrl`.
+4. Confirm the gateway logs include `Velay tunnel connected` followed by `Velay tunnel registered`. Registration publishes the returned Velay URL to `ingress.publicBaseUrl`.
 
 For an HTTP bridge smoke test, send a request to the registered Velay public URL and confirm it reaches the loopback gateway, for example:
 
@@ -249,7 +249,7 @@ bun -e 'const ws = new WebSocket(process.argv[1]); ws.onopen = () => { console.l
   "wss://<velay-host>/<assistant-id>/webhooks/twilio/relay?callSessionId=session-123&token=<edge-token>"
 ```
 
-For a real Twilio call, expose local Velay with a public HTTPS/WSS tunnel and configure the platform Velay service with that origin as `VELAY_PUBLIC_BASE_URL`. After the assistant re-registers, Twilio should fetch `/webhooks/twilio/voice` and open `/webhooks/twilio/relay` or `/webhooks/twilio/media-stream/...` through the Velay URL. Keep using ngrok or another custom tunnel in `ingress.publicBaseUrl` when you need Telegram, OAuth, email, or non-Twilio webhook ingress.
+For a real Twilio call, expose local Velay with a public HTTPS/WSS tunnel and configure the platform Velay service with that origin as `VELAY_PUBLIC_BASE_URL`. After the assistant re-registers, Twilio should fetch `/webhooks/twilio/voice` and open `/webhooks/twilio/relay` or `/webhooks/twilio/media-stream/...` through the Velay URL. Use ngrok or another custom tunnel in `ingress.publicBaseUrl` only for local/self-hosted workflows that are not routed through Velay.
 
 ## Ingress Boundary Guarantees
 

package/bun.lock

@@ -7,6 +7,7 @@
       "dependencies": {
         "@vellumai/assistant-client": "file:../packages/assistant-client",
         "@vellumai/ces-client": "file:../packages/ces-client",
+        "@vellumai/ipc-server-utils": "file:../packages/ipc-server-utils",
         "@vellumai/service-contracts": "file:../packages/service-contracts",
         "@vellumai/slack-text": "file:../packages/slack-text",
         "@vellumai/twilio-client": "file:../packages/twilio-client",
@@ -209,6 +210,8 @@
 
     "@vellumai/ces-client": ["@vellumai/ces-client@file:../packages/ces-client", { "dependencies": { "@vellumai/service-contracts": "file:../service-contracts" }, "devDependencies": { "@types/bun": "1.2.4", "typescript": "5.7.3" } }],
 
+    "@vellumai/ipc-server-utils": ["@vellumai/ipc-server-utils@file:../packages/ipc-server-utils", { "devDependencies": { "@types/bun": "1.3.10", "typescript": "5.9.3" } }],
+
     "@vellumai/service-contracts": ["@vellumai/service-contracts@file:../packages/service-contracts", { "dependencies": { "zod": "4.3.6" }, "devDependencies": { "@types/bun": "1.2.4", "typescript": "5.7.3" } }],
 
     "@vellumai/slack-text": ["@vellumai/slack-text@file:../packages/slack-text", { "devDependencies": { "@types/bun": "1.3.10", "typescript": "5.9.3" } }],
@@ -497,10 +500,12 @@
 
     "@vellumai/ces-client/@types/bun": ["@types/bun@1.2.4", "", { "dependencies": { "bun-types": "1.2.4" } }, "sha512-QtuV5OMR8/rdKJs213iwXDpfVvnskPXY/S0ZiFbsTjQZycuqPbMW8Gf/XhLfwE5njW8sxI2WjISURXPlHypMFA=="],
 
-    "@vellumai/ces-client/@vellumai/service-contracts": ["@vellumai/service-contracts@file:../packages/service-contracts", {}],
+    "@vellumai/ces-client/@vellumai/service-contracts": ["@vellumai/service-contracts@file:../packages/service-contracts", { "dependencies": { "zod": "4.3.6" }, "devDependencies": { "@types/bun": "1.2.4", "typescript": "5.7.3" } }],
 
     "@vellumai/ces-client/typescript": ["typescript@5.7.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-84MVSjMEHP+FQRPy3pX9sTVV/INIex71s9TL2Gm5FG/WG1SqXeKyZ0k7/blY/4FdOzI12CBy1vGc4og/eus0fw=="],
 
+    "@vellumai/ipc-server-utils/@types/bun": ["@types/bun@1.3.10", "", { "dependencies": { "bun-types": "1.3.10" } }, "sha512-0+rlrUrOrTSskibryHbvQkDOWRJwJZqZlxrUs1u4oOoTln8+WIXBPmAuCF35SWB2z4Zl3E84Nl/D0P7803nigQ=="],
+
     "@vellumai/service-contracts/@types/bun": ["@types/bun@1.2.4", "", { "dependencies": { "bun-types": "1.2.4" } }, "sha512-QtuV5OMR8/rdKJs213iwXDpfVvnskPXY/S0ZiFbsTjQZycuqPbMW8Gf/XhLfwE5njW8sxI2WjISURXPlHypMFA=="],
 
     "@vellumai/service-contracts/typescript": ["typescript@5.7.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-84MVSjMEHP+FQRPy3pX9sTVV/INIex71s9TL2Gm5FG/WG1SqXeKyZ0k7/blY/4FdOzI12CBy1vGc4og/eus0fw=="],
@@ -567,6 +572,8 @@
 
     "@vellumai/ces-client/@types/bun/bun-types": ["bun-types@1.2.4", "", { "dependencies": { "@types/node": "*", "@types/ws": "~8.5.10" } }, "sha512-nDPymR207ZZEoWD4AavvEaa/KZe/qlrbMSchqpQwovPZCKc7pwMoENjEtHgMKaAjJhy+x6vfqSBA1QU3bJgs0Q=="],
 
+    "@vellumai/ipc-server-utils/@types/bun/bun-types": ["bun-types@1.3.10", "", { "dependencies": { "@types/node": "*" } }, "sha512-tcpfCCl6XWo6nCVnpcVrxQ+9AYN1iqMIzgrSKYMB/fjLtV2eyAVEg7AxQJuCq/26R6HpKWykQXuSOq/21RYcbg=="],
+
     "@vellumai/service-contracts/@types/bun/bun-types": ["bun-types@1.2.4", "", { "dependencies": { "@types/node": "*", "@types/ws": "~8.5.10" } }, "sha512-nDPymR207ZZEoWD4AavvEaa/KZe/qlrbMSchqpQwovPZCKc7pwMoENjEtHgMKaAjJhy+x6vfqSBA1QU3bJgs0Q=="],
 
     "@vellumai/slack-text/@types/bun/bun-types": ["bun-types@1.3.10", "", { "dependencies": { "@types/node": "*" } }, "sha512-tcpfCCl6XWo6nCVnpcVrxQ+9AYN1iqMIzgrSKYMB/fjLtV2eyAVEg7AxQJuCq/26R6HpKWykQXuSOq/21RYcbg=="],

package/knip.json

@@ -4,6 +4,7 @@
   "ignoreDependencies": [
     "@vellumai/assistant-client",
     "@vellumai/ces-client",
+    "@vellumai/ipc-server-utils",
     "@vellumai/service-contracts",
     "@vellumai/slack-text",
     "@vellumai/twilio-client"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -26,6 +26,7 @@
   "dependencies": {
     "@vellumai/assistant-client": "file:../packages/assistant-client",
     "@vellumai/ces-client": "file:../packages/ces-client",
+    "@vellumai/ipc-server-utils": "file:../packages/ipc-server-utils",
     "@vellumai/service-contracts": "file:../packages/service-contracts",
     "@vellumai/slack-text": "file:../packages/slack-text",
     "@vellumai/twilio-client": "file:../packages/twilio-client",

package/src/__tests__/config-file-watcher.test.ts

@@ -144,7 +144,7 @@ describe("Twilio webhook sync config-change triggers", () => {
     expect(shouldSyncTwilioPhoneWebhooksAfterConfigChange(event)).toBe(true);
   });
 
-  test("syncs when the Twilio-specific public ingress changes", () => {
+  test("syncs when Velay-managed public ingress changes", () => {
     const event = makeEvent(["ingress"], {
       ingress: ["publicBaseUrl", "publicBaseUrlManagedBy"],
     });

package/src/__tests__/contact-prompt-submit.test.ts

@@ -0,0 +1,349 @@
+/**
+ * Tests for POST /v1/contacts/prompt/submit.
+ *
+ * Covers the key contact-first resolution logic:
+ * - Guardian prompts always bind to the existing guardian contact.
+ * - Guardian prompts conflict (409) when the channel belongs to another contact.
+ * - Non-guardian prompts create or reuse contacts via channel lookup.
+ * - All writes are dual-written to the gateway DB.
+ */
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  test,
+} from "bun:test";
+import { Database } from "bun:sqlite";
+
+import { initSigningKey } from "../auth/token-service.js";
+
+initSigningKey(Buffer.from("test-signing-key-at-least-32-bytes-long-xx"));
+
+// ---------------------------------------------------------------------------
+// Mock assistant DB proxy with a real in-memory SQLite.
+// ---------------------------------------------------------------------------
+
+let testAssistantDb: Database | null = null;
+
+mock.module("../db/assistant-db-proxy.js", () => ({
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async assistantDbQuery(sql: string, bind?: any[]) {
+    if (!testAssistantDb) throw new Error("test assistant DB not initialized");
+    const stmt = testAssistantDb.prepare(sql);
+    return bind ? stmt.all(...bind) : stmt.all();
+  },
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async assistantDbRun(sql: string, bind?: any[]) {
+    if (!testAssistantDb) throw new Error("test assistant DB not initialized");
+    const stmt = testAssistantDb.prepare(sql);
+    const result = bind ? stmt.run(...bind) : stmt.run();
+    return { changes: result.changes, lastInsertRowid: Number(result.lastInsertRowid) };
+  },
+}));
+
+// ---------------------------------------------------------------------------
+// Mock IPC so resolve_contact_prompt doesn't try to dial a real socket.
+// ---------------------------------------------------------------------------
+
+const ipcMock = mock(async () => ({ resolved: true }));
+
+mock.module("../ipc/assistant-client.js", () => ({
+  ipcCallAssistant: ipcMock,
+}));
+
+// ---------------------------------------------------------------------------
+// Imports that depend on the mocks above.
+// ---------------------------------------------------------------------------
+
+const { handleContactPromptSubmit } = await import(
+  "../http/routes/contact-prompt.js"
+);
+const { initGatewayDb, getGatewayDb, resetGatewayDb } = await import(
+  "../db/connection.js"
+);
+const { contactChannels: gwContactChannels, contacts: gwContacts } =
+  await import("../db/schema.js");
+const { eq } = await import("drizzle-orm");
+
+// ---------------------------------------------------------------------------
+// Schema helpers
+// ---------------------------------------------------------------------------
+
+function initAssistantDb(): Database {
+  const db = new Database(":memory:");
+  db.exec("PRAGMA foreign_keys=ON");
+  db.exec(`
+    CREATE TABLE contacts (
+      id TEXT PRIMARY KEY,
+      display_name TEXT NOT NULL,
+      notes TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      role TEXT NOT NULL DEFAULT 'contact',
+      principal_id TEXT,
+      user_file TEXT,
+      contact_type TEXT NOT NULL DEFAULT 'human'
+    )
+  `);
+  db.exec(`
+    CREATE TABLE contact_channels (
+      id TEXT PRIMARY KEY,
+      contact_id TEXT NOT NULL REFERENCES contacts(id) ON DELETE CASCADE,
+      type TEXT NOT NULL,
+      address TEXT NOT NULL,
+      is_primary INTEGER NOT NULL DEFAULT 0,
+      external_user_id TEXT,
+      external_chat_id TEXT,
+      status TEXT NOT NULL DEFAULT 'unverified',
+      policy TEXT NOT NULL DEFAULT 'allow',
+      verified_at INTEGER,
+      verified_via TEXT,
+      invite_id TEXT,
+      revoked_reason TEXT,
+      blocked_reason TEXT,
+      last_seen_at INTEGER,
+      interaction_count INTEGER NOT NULL DEFAULT 0,
+      last_interaction INTEGER,
+      updated_at INTEGER,
+      created_at INTEGER NOT NULL
+    )
+  `);
+  db.exec(
+    `CREATE UNIQUE INDEX idx_contact_channels_type_address ON contact_channels(type, address)`,
+  );
+  return db;
+}
+
+// ---------------------------------------------------------------------------
+// Request factory
+// ---------------------------------------------------------------------------
+
+function makeRequest(body: Record<string, unknown>): Request {
+  return new Request("http://localhost:7830/v1/contacts/prompt/submit", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Suite setup
+// ---------------------------------------------------------------------------
+
+beforeAll(async () => {
+  await initGatewayDb();
+});
+
+afterAll(() => {
+  resetGatewayDb();
+});
+
+beforeEach(() => {
+  testAssistantDb = initAssistantDb();
+  ipcMock.mockClear();
+
+  const gwDb = getGatewayDb();
+  gwDb.delete(gwContactChannels).run();
+  gwDb.delete(gwContacts).run();
+});
+
+afterEach(() => {
+  testAssistantDb?.close();
+  testAssistantDb = null;
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("handleContactPromptSubmit", () => {
+  test("guardian prompt — creates channel bound to existing guardian contact", async () => {
+    const now = Date.now();
+    // Seed an existing guardian contact in the assistant DB.
+    testAssistantDb!.run(
+      `INSERT INTO contacts (id, display_name, role, contact_type, created_at, updated_at)
+       VALUES ('guardian-1', 'Vargas', 'guardian', 'human', ?, ?)`,
+      [now, now],
+    );
+
+    const res = await handleContactPromptSubmit(
+      makeRequest({ requestId: "req-1", address: "+15551234567", channelType: "phone", role: "guardian" }),
+    );
+
+    expect(res.status).toBe(200);
+    const body = await res.json() as Record<string, unknown>;
+    expect(body.accepted).toBe(true);
+
+    // Channel should be created in assistant DB pointing to guardian.
+    const channels = testAssistantDb!
+      .prepare(`SELECT contact_id FROM contact_channels WHERE type = 'phone' AND address = ?`)
+      .all("+15551234567") as { contact_id: string }[];
+    expect(channels).toHaveLength(1);
+    expect(channels[0].contact_id).toBe("guardian-1");
+
+    // IPC should have been called with the guardian contactId.
+    expect(ipcMock).toHaveBeenCalledTimes(1);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const ipcCall = (ipcMock.mock.calls as any[][])[0][1] as { body: Record<string, unknown> };
+    expect(ipcCall.body.contactId).toBe("guardian-1");
+  });
+
+  test("guardian prompt — reuses channel already bound to guardian", async () => {
+    const now = Date.now();
+    testAssistantDb!.run(
+      `INSERT INTO contacts (id, display_name, role, contact_type, created_at, updated_at)
+       VALUES ('guardian-1', 'Vargas', 'guardian', 'human', ?, ?)`,
+      [now, now],
+    );
+    testAssistantDb!.run(
+      `INSERT INTO contact_channels (id, contact_id, type, address, is_primary, status, policy, interaction_count, created_at, updated_at)
+       VALUES ('chan-1', 'guardian-1', 'phone', '+15551234567', 1, 'active', 'allow', 5, ?, ?)`,
+      [now, now],
+    );
+
+    const res = await handleContactPromptSubmit(
+      makeRequest({ requestId: "req-2", address: "+15551234567", channelType: "phone", role: "guardian" }),
+    );
+
+    expect(res.status).toBe(200);
+    const body = await res.json() as Record<string, unknown>;
+    expect(body.accepted).toBe(true);
+
+    // No new channel should have been inserted.
+    const channels = testAssistantDb!
+      .prepare(`SELECT id FROM contact_channels WHERE type = 'phone'`)
+      .all() as { id: string }[];
+    expect(channels).toHaveLength(1);
+    expect(channels[0].id).toBe("chan-1");
+  });
+
+  test("guardian prompt — 409 when channel already belongs to another contact", async () => {
+    const now = Date.now();
+    // Guardian contact.
+    testAssistantDb!.run(
+      `INSERT INTO contacts (id, display_name, role, contact_type, created_at, updated_at)
+       VALUES ('guardian-1', 'Vargas', 'guardian', 'human', ?, ?)`,
+      [now, now],
+    );
+    // A different (orphaned or stale) contact that owns the channel.
+    testAssistantDb!.run(
+      `INSERT INTO contacts (id, display_name, role, contact_type, created_at, updated_at)
+       VALUES ('other-1', 'Orphan', 'contact', 'human', ?, ?)`,
+      [now, now],
+    );
+    testAssistantDb!.run(
+      `INSERT INTO contact_channels (id, contact_id, type, address, is_primary, status, policy, interaction_count, created_at, updated_at)
+       VALUES ('chan-other', 'other-1', 'phone', '+15551234567', 1, 'unverified', 'allow', 0, ?, ?)`,
+      [now, now],
+    );
+
+    const res = await handleContactPromptSubmit(
+      makeRequest({ requestId: "req-3", address: "+15551234567", channelType: "phone", role: "guardian" }),
+    );
+
+    expect(res.status).toBe(409);
+    const body = await res.json() as Record<string, unknown>;
+    expect(body.accepted).toBe(false);
+
+    // The stale channel must not have been deleted.
+    const channels = testAssistantDb!
+      .prepare(`SELECT id FROM contact_channels WHERE type = 'phone'`)
+      .all() as { id: string }[];
+    expect(channels).toHaveLength(1);
+    expect(channels[0].id).toBe("chan-other");
+
+    // IPC should have been called with an error so the CLI doesn't hang.
+    expect(ipcMock).toHaveBeenCalledTimes(1);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const ipcCall = (ipcMock.mock.calls as any[][])[0][1] as { body: Record<string, unknown> };
+    expect(typeof ipcCall.body.error).toBe("string");
+  });
+
+  test("non-guardian prompt — creates new contact and channel", async () => {
+    const res = await handleContactPromptSubmit(
+      makeRequest({
+        requestId: "req-4",
+        address: "alice@example.com",
+        channelType: "email",
+        role: "trusted-contact",
+        displayName: "Alice",
+      }),
+    );
+
+    expect(res.status).toBe(200);
+
+    const contacts = testAssistantDb!
+      .prepare(`SELECT id, role FROM contacts WHERE display_name = 'Alice'`)
+      .all() as { id: string; role: string }[];
+    expect(contacts).toHaveLength(1);
+    expect(contacts[0].role).toBe("contact");
+
+    const channels = testAssistantDb!
+      .prepare(`SELECT contact_id FROM contact_channels WHERE type = 'email' AND address = ?`)
+      .all("alice@example.com") as { contact_id: string }[];
+    expect(channels).toHaveLength(1);
+    expect(channels[0].contact_id).toBe(contacts[0].id);
+  });
+
+  test("non-guardian prompt — reuses existing contact when channel already known", async () => {
+    const now = Date.now();
+    testAssistantDb!.run(
+      `INSERT INTO contacts (id, display_name, role, contact_type, created_at, updated_at)
+       VALUES ('contact-1', 'Alice', 'contact', 'human', ?, ?)`,
+      [now, now],
+    );
+    testAssistantDb!.run(
+      `INSERT INTO contact_channels (id, contact_id, type, address, is_primary, status, policy, interaction_count, created_at, updated_at)
+       VALUES ('chan-alice', 'contact-1', 'email', 'alice@example.com', 1, 'active', 'allow', 3, ?, ?)`,
+      [now, now],
+    );
+
+    const res = await handleContactPromptSubmit(
+      makeRequest({ requestId: "req-5", address: "alice@example.com", channelType: "email" }),
+    );
+
+    expect(res.status).toBe(200);
+
+    // Should not have created a second contact.
+    const contacts = testAssistantDb!
+      .prepare(`SELECT id FROM contacts`)
+      .all() as { id: string }[];
+    expect(contacts).toHaveLength(1);
+    expect(contacts[0].id).toBe("contact-1");
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const ipcCall = (ipcMock.mock.calls as any[][])[0][1] as { body: Record<string, unknown> };
+    expect(ipcCall.body.contactId).toBe("contact-1");
+  });
+
+  test("gateway DB receives dual-write for new contact and channel", async () => {
+    const now = Date.now();
+    testAssistantDb!.run(
+      `INSERT INTO contacts (id, display_name, role, contact_type, created_at, updated_at)
+       VALUES ('guardian-1', 'Vargas', 'guardian', 'human', ?, ?)`,
+      [now, now],
+    );
+
+    // Also seed guardian in gateway DB so FK is satisfied.
+    getGatewayDb()
+      .insert(gwContacts)
+      .values({ id: "guardian-1", displayName: "Vargas", role: "guardian", createdAt: now, updatedAt: now })
+      .run();
+
+    await handleContactPromptSubmit(
+      makeRequest({ requestId: "req-6", address: "+15559876543", channelType: "phone", role: "guardian" }),
+    );
+
+    const gwChannels = getGatewayDb()
+      .select()
+      .from(gwContactChannels)
+      .where(eq(gwContactChannels.address, "+15559876543"))
+      .all();
+    expect(gwChannels).toHaveLength(1);
+    expect(gwChannels[0].contactId).toBe("guardian-1");
+  });
+});