@vellumai/assistant 0.4.29 → 0.4.31

package/docs/runbook-trusted-contacts.md

@@ -1,12 +1,17 @@
 # Trusted Contacts — Operator Runbook
 
-Operational procedures for inspecting, managing, and debugging the trusted contact access flow. All HTTP commands use the gateway API (default `http://localhost:7830`) with bearer authentication.
+Operational procedures for inspecting, managing, and debugging the trusted contact access flow. HTTP commands use the assistant runtime API (default `http://localhost:7821`) with bearer authentication.
+
+> **Note:** The `/v1/contacts` endpoints are served by the assistant runtime, not
+> the gateway. If you prefer to route through the gateway (`localhost:7830`), set
+> `GATEWAY_RUNTIME_PROXY_ENABLED=true` in the gateway environment — the proxy is
+> disabled by default and these routes will 404 without it.
 
 ## Prerequisites
 
 ```bash
-# Base URL (adjust if using a non-default port)
-BASE=http://localhost:7830
+# Base URL — assistant runtime (adjust if using a non-default port)
+BASE=http://localhost:7821
 
 # Bearer token: if running via the assistant's shell tools, $GATEWAY_AUTH_TOKEN
 # is injected automatically. For manual operator use, mint a token via the CLI
@@ -14,51 +19,71 @@ BASE=http://localhost:7830
 TOKEN=$GATEWAY_AUTH_TOKEN
 ```
 
-## 1. Inspect Trusted Contacts (Members)
+## 1. Inspect Trusted Contacts
 
 ### List all active trusted contacts
 
 ```bash
-curl -s "$BASE/v1/ingress/members?status=active" \
+curl -s "$BASE/v1/contacts?role=contact" \
   -H "Authorization: Bearer $TOKEN" | jq
 ```
 
-### Filter by channel
+### Filter by channel type
 
 ```bash
 # Telegram contacts only
-curl -s "$BASE/v1/ingress/members?sourceChannel=telegram&status=active" \
+curl -s "$BASE/v1/contacts?channelType=telegram" \
   -H "Authorization: Bearer $TOKEN" | jq
 
 # SMS contacts only
-curl -s "$BASE/v1/ingress/members?sourceChannel=sms&status=active" \
+curl -s "$BASE/v1/contacts?channelType=sms" \
   -H "Authorization: Bearer $TOKEN" | jq
 ```
 
-### List all members (including revoked and blocked)
+### List all contacts (including revoked and blocked)
 
 ```bash
-curl -s "$BASE/v1/ingress/members" \
+curl -s "$BASE/v1/contacts" \
   -H "Authorization: Bearer $TOKEN" | jq
 ```
 
+### Via CLI
+
+```bash
+vellum contacts list --role contact
+```
+
 Response shape:
 
 ```json
 {
   "ok": true,
-  "members": [
+  "contacts": [
     {
       "id": "uuid",
-      "sourceChannel": "telegram",
-      "externalUserId": "123456789",
-      "externalChatId": "123456789",
       "displayName": "Alice",
-      "username": "alice_handle",
-      "status": "active",
-      "policy": "allow",
-      "lastSeenAt": 1700000000000,
-      "createdAt": 1699000000000
+      "notes": null,
+      "lastInteraction": 1700000000000,
+      "interactionCount": 12,
+      "createdAt": 1699000000000,
+      "updatedAt": 1700000000000,
+      "role": "contact",
+      "channels": [
+        {
+          "id": "channel-uuid",
+          "contactId": "uuid",
+          "type": "telegram",
+          "address": "alice_handle",
+          "isPrimary": true,
+          "externalUserId": "123456789",
+          "externalChatId": "123456789",
+          "status": "active",
+          "policy": "allow",
+          "verifiedAt": 1699500000000,
+          "lastSeenAt": 1700000000000,
+          "createdAt": 1699000000000
+        }
+      ]
     }
   ]
 }
@@ -109,29 +134,29 @@ sqlite3 ~/.vellum/workspace/data/db/assistant.db \
 
 ### Via HTTP API
 
-First, find the member's `id` from the list endpoint, then revoke:
+First, find the contact and its channel ID from the list endpoint, then revoke the channel:
 
 ```bash
-# Find the member
-MEMBER_ID=$(curl -s "$BASE/v1/ingress/members?sourceChannel=telegram&status=active" \
-  -H "Authorization: Bearer $TOKEN" | jq -r '.members[] | select(.externalUserId == "TARGET_USER_ID") | .id')
+# Find the contact's channel ID
+CHANNEL_ID=$(curl -s "$BASE/v1/contacts?channelType=telegram" \
+  -H "Authorization: Bearer $TOKEN" | jq -r '.contacts[] | select(.channels[] | select(.externalUserId == "TARGET_USER_ID")) | .channels[] | select(.externalUserId == "TARGET_USER_ID") | .id')
 
 # Revoke with reason
-curl -s -X DELETE "$BASE/v1/ingress/members/$MEMBER_ID" \
+curl -s -X PATCH "$BASE/v1/contacts/channels/$CHANNEL_ID" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"reason": "Revoked by operator"}' | jq
+  -d '{"status": "revoked", "reason": "Revoked by operator"}' | jq
 ```
 
-### Block a member (stronger than revoke)
+### Block a contact channel (stronger than revoke)
 
-Blocking prevents the member from re-entering the flow without explicit unblocking.
+Blocking prevents the contact from re-entering the flow without explicit unblocking.
 
 ```bash
-curl -s -X POST "$BASE/v1/ingress/members/$MEMBER_ID/block" \
+curl -s -X PATCH "$BASE/v1/contacts/channels/$CHANNEL_ID" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"reason": "Blocked by operator"}' | jq
+  -d '{"status": "blocked", "reason": "Blocked by operator"}' | jq
 ```
 
 ### Via SQLite (emergency)
@@ -229,35 +254,43 @@ sqlite3 ~/.vellum/workspace/data/db/assistant.db \
 
 ## 7. Manually Add a Trusted Contact (Bypass Verification)
 
-If the verification flow cannot be completed, an operator can directly create an active member:
+If the verification flow cannot be completed, an operator can directly create an active contact:
 
 ```bash
-curl -s -X POST "$BASE/v1/ingress/members" \
+curl -s -X POST "$BASE/v1/contacts" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
-    "sourceChannel": "telegram",
-    "externalUserId": "123456789",
-    "externalChatId": "123456789",
     "displayName": "Alice",
-    "policy": "allow",
-    "status": "active"
+    "role": "contact",
+    "channels": [{
+      "type": "telegram",
+      "address": "alice_handle",
+      "externalUserId": "123456789",
+      "externalChatId": "123456789",
+      "status": "active",
+      "policy": "allow"
+    }]
   }' | jq
 ```
 
-For SMS contacts, use the E.164 phone number as the external user/chat ID:
+For SMS contacts, use the E.164 phone number as the address and external user/chat ID:
 
 ```bash
-curl -s -X POST "$BASE/v1/ingress/members" \
+curl -s -X POST "$BASE/v1/contacts" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
-    "sourceChannel": "sms",
-    "externalUserId": "+15551234567",
-    "externalChatId": "+15551234567",
     "displayName": "Bob",
-    "policy": "allow",
-    "status": "active"
+    "role": "contact",
+    "channels": [{
+      "type": "sms",
+      "address": "+15551234567",
+      "externalUserId": "+15551234567",
+      "externalChatId": "+15551234567",
+      "status": "active",
+      "policy": "allow"
+    }]
   }' | jq
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.4.29",
+  "version": "0.4.31",
   "type": "module",
   "bin": {
     "vellum": "./src/index.ts"

package/scripts/ipc/check-swift-decoder-drift.ts

@@ -49,9 +49,8 @@ const SWIFT_OMIT_ALLOWLIST = new Set<string>([
   "heartbeat_alert",
   // Guardian verification — daemon-internal for Telegram channel setup
   "guardian_verification_response",
-  // Ingress invite/member management — not yet consumed by the macOS client
-  "ingress_invite_response",
-  "ingress_member_response",
+  // Contacts invite management — not yet consumed by the macOS client
+  "contacts_invite_response",
   // Inbox escalation — not yet consumed by the macOS client
   "assistant_inbox_escalation_response",
   // Work item messages — not yet consumed by the macOS client

package/scripts/test.sh

@@ -166,7 +166,7 @@ printf '%s\n' "${test_files[@]}" | xargs -P "${WORKERS}" -I {} bash -c '
     if grep -q "^(fail)" "${out_file}" 2>/dev/null; then
       echo "${test_file}" >> "${results_dir}/failures"
       echo "  ✗ ${base} (killed after ${per_test_timeout}s — tests failed and process hung)"
-    elif grep -qE "^Ran [0-9]+ tests across" "${out_file}" 2>/dev/null; then
+    elif grep -qE "^Ran [0-9]+ tests? across" "${out_file}" 2>/dev/null; then
       echo "  ⚠ ${base} (tests passed but process hung after ${per_test_timeout}s — likely open handles)"
     else
       echo "${test_file}" >> "${results_dir}/failures"

package/src/__tests__/__snapshots__/ipc-snapshot.test.ts.snap

@@ -967,28 +967,14 @@ exports[`IPC message snapshots ClientMessage types dictation_request serializes
 }
 `;
 
-exports[`IPC message snapshots ClientMessage types ingress_invite serializes to expected JSON 1`] = `
+exports[`IPC message snapshots ClientMessage types contacts_invite serializes to expected JSON 1`] = `
 {
   "action": "create",
   "expiresInMs": 86400000,
   "maxUses": 5,
   "note": "Test invite",
   "sourceChannel": "telegram",
-  "type": "ingress_invite",
-}
-`;
-
-exports[`IPC message snapshots ClientMessage types ingress_member serializes to expected JSON 1`] = `
-{
-  "action": "upsert",
-  "displayName": "Test User",
-  "externalChatId": "chat-456",
-  "externalUserId": "user-123",
-  "policy": "allow",
-  "sourceChannel": "telegram",
-  "status": "active",
-  "type": "ingress_member",
-  "username": "testuser",
+  "type": "contacts_invite",
 }
 `;
 
@@ -2844,7 +2830,7 @@ exports[`IPC message snapshots ServerMessage types dictation_response serializes
 }
 `;
 
-exports[`IPC message snapshots ServerMessage types ingress_invite_response serializes to expected JSON 1`] = `
+exports[`IPC message snapshots ServerMessage types contacts_invite_response serializes to expected JSON 1`] = `
 {
   "invite": {
     "createdAt": 1700000000,
@@ -2859,26 +2845,7 @@ exports[`IPC message snapshots ServerMessage types ingress_invite_response seria
     "useCount": 0,
   },
   "success": true,
-  "type": "ingress_invite_response",
-}
-`;
-
-exports[`IPC message snapshots ServerMessage types ingress_member_response serializes to expected JSON 1`] = `
-{
-  "member": {
-    "createdAt": 1700000000,
-    "displayName": "Test User",
-    "externalChatId": "chat-456",
-    "externalUserId": "user-123",
-    "id": "mem-001",
-    "lastSeenAt": 1700000000,
-    "policy": "allow",
-    "sourceChannel": "telegram",
-    "status": "active",
-    "username": "testuser",
-  },
-  "success": true,
-  "type": "ingress_member_response",
+  "type": "contacts_invite_response",
 }
 `;
 

package/src/__tests__/actor-token-service.test.ts

@@ -449,14 +449,15 @@ describe("resolveLocalIpcAuthContext", () => {
     );
   });
 
-  test("actorPrincipalId is undefined when no vellum binding exists", () => {
+  test("actorPrincipalId is auto-created via self-heal when no vellum binding exists", () => {
     // Reset DB to ensure no binding
     resetDb();
     initializeDb();
 
     const ctx = resolveLocalIpcAuthContext("session-123");
-    // When no binding exists, actorPrincipalId is not set
-    expect(ctx.actorPrincipalId).toBeUndefined();
+    // Self-heal creates a vellum guardian binding automatically
+    expect(ctx.actorPrincipalId).toBeDefined();
+    expect(ctx.actorPrincipalId).toMatch(/^vellum-principal-/);
   });
 
   test("sessionId matches the provided argument", () => {

package/src/__tests__/app-executors.test.ts

@@ -180,28 +180,18 @@ describe("executeAppCreate", () => {
     expect(capturedPages).toEqual({ "settings.html": "<div/>" });
   });
 
-  test('maps type "site" to appType "site"', async () => {
-    let capturedType: "app" | "site" | undefined;
+  test("defaults html to minimal scaffold when omitted", async () => {
+    let capturedHtml: string | undefined;
     const store = makeMockStore({
       createApp: (params) => {
-        capturedType = params.appType;
+        capturedHtml = params.htmlDefinition;
         return makeApp({ name: params.name });
       },
     });
-    await executeAppCreate({ name: "Site", html: "<p/>", type: "site" }, store);
-    expect(capturedType).toBe("site");
-  });
-
-  test('defaults appType to "app" when type is not "site"', async () => {
-    let capturedType: "app" | "site" | undefined;
-    const store = makeMockStore({
-      createApp: (params) => {
-        capturedType = params.appType;
-        return makeApp({ name: params.name });
-      },
-    });
-    await executeAppCreate({ name: "App", html: "<p/>" }, store);
-    expect(capturedType).toBe("app");
+    await executeAppCreate({ name: "No HTML" }, store);
+    expect(capturedHtml).toBe(
+      "<!DOCTYPE html><html><head></head><body></body></html>",
+    );
   });
 });
 

package/src/__tests__/assistant-feature-flags-integration.test.ts

@@ -146,16 +146,20 @@ describe("buildSystemPrompt assistant feature flag filtering", () => {
 
     currentConfig = {
       sandbox: { enabled: false, backend: "native" },
-      assistantFeatureFlagValues: { [DECLARED_FLAG_KEY]: false },
+      assistantFeatureFlagValues: {
+        [DECLARED_FLAG_KEY]: false,
+        "feature_flags.twitter.enabled": true,
+      },
     };
 
     const result = buildSystemPrompt();
 
+    // twitter is explicitly enabled, declared flagged skill is explicitly off
     expect(result).toContain('id="twitter"');
     expect(result).not.toContain(`id="${DECLARED_SKILL_ID}"`);
   });
 
-  test("all skills visible when no flag overrides set", () => {
+  test("declared skills hidden when no flag overrides set (registry defaults to false)", () => {
     createSkillOnDisk(
       DECLARED_SKILL_ID,
       "Hatch New Assistant",
@@ -169,8 +173,9 @@ describe("buildSystemPrompt assistant feature flag filtering", () => {
 
     const result = buildSystemPrompt();
 
-    expect(result).toContain(`id="${DECLARED_SKILL_ID}"`);
-    expect(result).toContain('id="twitter"');
+    // Both skills are declared in the registry with defaultEnabled: false
+    expect(result).not.toContain(`id="${DECLARED_SKILL_ID}"`);
+    expect(result).not.toContain('id="twitter"');
   });
 
   test("flagged-off skills hidden when all flags are OFF", () => {
@@ -227,7 +232,7 @@ describe("buildSystemPrompt assistant feature flag filtering", () => {
     expect(result).not.toContain('id="browser"');
   });
 
-  test("undeclared flags with no persisted override default to enabled", () => {
+  test("declared flags with no persisted override use registry default", () => {
     createSkillOnDisk("browser", "Browser", "Web browsing automation");
 
     currentConfig = {
@@ -236,7 +241,8 @@ describe("buildSystemPrompt assistant feature flag filtering", () => {
 
     const result = buildSystemPrompt();
 
-    expect(result).toContain('id="browser"');
+    // browser is declared in the registry with defaultEnabled: false
+    expect(result).not.toContain('id="browser"');
   });
 });
 
@@ -265,10 +271,12 @@ describe("isAssistantFeatureFlagEnabled", () => {
 
   test("missing persisted value falls back to defaults registry defaultEnabled", () => {
     // No explicit config at all — should fall back to defaults registry
-    // which has defaultEnabled: true for hatch-new-assistant
+    // which has defaultEnabled: false for hatch-new-assistant
     const config = {} as any;
 
-    expect(isAssistantFeatureFlagEnabled(DECLARED_FLAG_KEY, config)).toBe(true);
+    expect(isAssistantFeatureFlagEnabled(DECLARED_FLAG_KEY, config)).toBe(
+      false,
+    );
   });
 
   test("unknown flag defaults to true when no persisted override", () => {
@@ -302,9 +310,9 @@ describe("legacy isSkillFeatureEnabled backward compat", () => {
     expect(isSkillFeatureEnabled(DECLARED_SKILL_ID, config)).toBe(false);
   });
 
-  test("enabled when no override set", () => {
+  test("disabled when no override set (registry default is false)", () => {
     const config = {} as any;
 
-    expect(isSkillFeatureEnabled(DECLARED_SKILL_ID, config)).toBe(true);
+    expect(isSkillFeatureEnabled(DECLARED_SKILL_ID, config)).toBe(false);
   });
 });

package/src/__tests__/browser-skill-endstate.test.ts

@@ -4,7 +4,16 @@
  * Locks the final invariants from the BROWSER_SKILL plan so that future
  * changes cannot silently regress any of the migration guarantees.
  */
-import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { afterAll, beforeAll, describe, expect, mock, test } from "bun:test";
+
+mock.module("../config/loader.js", () => ({
+  getConfig: () => ({
+    sandbox: { enabled: false, backend: "native" },
+    assistantFeatureFlagValues: {
+      "feature_flags.browser.enabled": true,
+    },
+  }),
+}));
 
 import {
   projectSkillTools,

package/src/__tests__/bundled-skill-retrieval-guard.test.ts

@@ -62,6 +62,7 @@ const GATEWAY_RETRIEVAL_BANLIST: Array<{
     bannedSnippets: [
       'curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/members',
       'curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/invites',
+      'curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/contacts/invites',
       'curl -s "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/telegram/config',
     ],
   },