@vellumai/assistant 0.4.29 → 0.4.30

package/ARCHITECTURE.md

@@ -433,31 +433,33 @@ External users who are not the guardian can gain access to the assistant through
 
 **Notification signals:** The flow emits signals at each lifecycle transition via `emitNotificationSignal()`:
 
-- `ingress.access_request` — non-member denied, guardian notified
+- `ingress.access_request` — unknown contact denied, guardian notified
 - `ingress.trusted_contact.guardian_decision` — guardian approved or denied
 - `ingress.trusted_contact.verification_sent` — code created and delivered
-- `ingress.trusted_contact.activated` — requester verified, member active
+- `ingress.trusted_contact.activated` — requester verified, contact active
 - `ingress.trusted_contact.denied` — guardian explicitly denied
 
 **HTTP API (for management):**
 
-| Endpoint                        | Method | Description                                                   |
-| ------------------------------- | ------ | ------------------------------------------------------------- |
-| `/v1/ingress/members`           | GET    | List trusted contacts (filterable by channel, status, policy) |
-| `/v1/ingress/members`           | POST   | Upsert a member (add/update trusted contact)                  |
-| `/v1/ingress/members/:id`       | DELETE | Revoke a trusted contact                                      |
-| `/v1/ingress/members/:id/block` | POST   | Block a member                                                |
+| Endpoint                    | Method | Description                                                      |
+| --------------------------- | ------ | ---------------------------------------------------------------- |
+| `/v1/contacts`              | GET    | List contacts (filterable by role, search by query/channel/etc.) |
+| `/v1/contacts`              | POST   | Create or update a contact                                       |
+| `/v1/contacts/:id`          | GET    | Get a contact by ID                                              |
+| `/v1/contacts/merge`        | POST   | Merge two contacts                                               |
+| `/v1/contacts/channels/:id` | PATCH  | Update a contact channel's status/policy                         |
 
 **Key source files:**
 
 | File                                                   | Purpose                                                                       |
 | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
-| `src/runtime/routes/inbound-message-handler.ts`        | Ingress ACL, non-member rejection, verification code interception             |
+| `src/runtime/routes/inbound-message-handler.ts`        | Ingress ACL, unknown-contact rejection, verification code interception        |
 | `src/runtime/routes/access-request-decision.ts`        | Guardian decision → verification session creation                             |
 | `src/runtime/routes/guardian-approval-interception.ts` | Routes guardian decisions (button + conversational) to access request handler |
 | `src/runtime/channel-guardian-service.ts`              | Verification challenge lifecycle, identity binding, rate limiting             |
-| `src/runtime/routes/ingress-routes.ts`                 | HTTP API handlers for member/invite management                                |
-| `src/runtime/ingress-service.ts`                       | Business logic for member CRUD                                                |
+| `src/runtime/routes/contact-routes.ts`                 | HTTP API handlers for contact and channel management                          |
+| `src/runtime/routes/invite-routes.ts`                  | HTTP API handlers for invite management                                       |
+| `src/runtime/invite-service.ts`                        | Business logic for invite operations                                          |
 | `src/contacts/contact-store.ts`                        | Contact read queries — lookup, search, list, and channel operations           |
 | `src/memory/channel-guardian-store.ts`                 | Approval request and verification challenge persistence                       |
 | `src/config/bundled-skills/contacts/SKILL.md`          | Unified skill for contact management, access control, and invite links        |
@@ -482,7 +484,7 @@ A complementary access-granting flow where the guardian proactively creates a sh
 ├─────────────────────────────────────────────────────────────┤
 │  Core Redemption Engine (invite-redemption-service.ts)       │
 │  Channel-agnostic token validation, expiry, use-count,       │
-│  channel-match enforcement, member creation/reactivation     │
+│  channel-match enforcement, contact activation/reactivation  │
 │  Returns: InviteRedemptionOutcome (discriminated union)      │
 │  Reply templates: invite-redemption-templates.ts             │
 └─────────────────────────────────────────────────────────────┘
@@ -496,12 +498,12 @@ A complementary access-granting flow where the guardian proactively creates a sh
 4. Guardian shares the link with the invitee out-of-band.
 5. Invitee clicks the link, opening Telegram which sends `/start iv_<token>` to the bot.
 6. The gateway forwards the message to `/channels/inbound`. The inbound handler calls `getTransport('telegram').extractInboundToken()` to parse the `iv_` token.
-7. The token is redeemed via `invite-redemption-service.ts`, which validates, creates an active member record, and returns a `redeemed` outcome.
+7. The token is redeemed via `invite-redemption-service.ts`, which validates, activates the contact, and returns a `redeemed` outcome.
 8. A deterministic welcome message is delivered to the invitee (bypasses the LLM pipeline).
 
 **Token prefix convention:** The `iv_` prefix distinguishes invite tokens from `gv_` (guardian verification) tokens. Both use the same Telegram `/start` deep-link mechanism but are routed to different handlers.
 
-**Inbound intercept points:** Invite token extraction runs early in the inbound handler, before ACL denial, so valid invites short-circuit the membership check. Two intercept branches handle: (a) non-members — the invite creates their first member record; (b) inactive members (revoked/pending) — the invite reactivates them.
+**Inbound intercept points:** Invite token extraction runs early in the inbound handler, before ACL denial, so valid invites short-circuit the contact check. Two intercept branches handle: (a) unknown contacts — the invite creates their first contact record; (b) inactive contacts (revoked/pending) — the invite reactivates them.
 
 **Channel adapter status:**
 
@@ -518,8 +520,8 @@ Voice invites use a short numeric code (4-10 digits, default 6) instead of a URL
 
 **Creation flow:**
 
-1. Guardian creates a voice invite via `POST /v1/ingress/invites` with `sourceChannel: "voice"` and `expectedExternalUserId` (E.164 phone).
-2. `ingress-service.ts` generates a cryptographically random numeric code (`generateVoiceCode`), hashes it with SHA-256 (`hashVoiceCode`), and stores only the hash.
+1. Guardian creates a voice invite via `POST /v1/contacts/invites` with `sourceChannel: "voice"` and `expectedExternalUserId` (E.164 phone).
+2. `invite-service.ts` generates a cryptographically random numeric code (`generateVoiceCode`), hashes it with SHA-256 (`hashVoiceCode`), and stores only the hash.
 3. The one-time plaintext `voiceCode` is returned in the creation response. The raw token is NOT returned for voice invites — redemption uses the identity-bound code flow exclusively.
 4. Guardian communicates the code to the invitee out-of-band.
 
@@ -528,7 +530,7 @@ Voice invites use a short numeric code (4-10 digits, default 6) instead of a URL
 1. Unknown caller dials in. `relay-server.ts` resolves trust via `resolveActorTrust`. Caller is `unknown`, no pending guardian challenge.
 2. The relay checks `findActiveVoiceInvites` for invites bound to the caller's phone number.
 3. If active, non-expired invites exist, the relay enters the `invite_redemption_pending` state (reuses the `verification_pending` connection state) and prompts the caller with personalized copy: `Welcome <friend-name>. Please enter the 6-digit code that <guardian-name> provided you to verify your identity.`
-4. `redeemVoiceInviteCode` validates: identity match, code hash match, expiry, use count. On success, an active member record is upserted and the call transitions to the normal call flow.
+4. `redeemVoiceInviteCode` validates: identity match, code hash match, expiry, use count. On success, the contact is activated and the call transitions to the normal call flow.
 5. On invalid/expired code, the caller hears deterministic failure copy: `Sorry, the code you provided is incorrect or has since expired. Please ask <guardian-name> for a new code. Goodbye.` and the call ends immediately.
 
 **Security invariants:**
@@ -536,24 +538,24 @@ Voice invites use a short numeric code (4-10 digits, default 6) instead of a URL
 - The plaintext voice code is returned exactly once at creation time and never stored.
 - Voice invites are identity-bound: `expectedExternalUserId` must match the caller's E.164 number. An attacker with the code but the wrong phone number cannot redeem.
 - Failure responses are intentionally generic (`invalid_or_expired`) to prevent oracle attacks.
-- Blocked members cannot bypass the guardian's explicit block via invite redemption.
+- Blocked contacts cannot bypass the guardian's explicit block via invite redemption.
 
 **Key source files:**
 
-| File                                                | Purpose                                                                                                         |
-| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `src/runtime/invite-redemption-service.ts`          | Core redemption engine — token validation, voice code redemption, member creation, discriminated-union outcomes |
-| `src/runtime/invite-redemption-templates.ts`        | Deterministic reply templates for each redemption outcome                                                       |
-| `src/runtime/channel-invite-transport.ts`           | Transport adapter registry with `buildShareableInvite` / `extractInboundToken` interface                        |
-| `src/runtime/channel-invite-transports/telegram.ts` | Telegram adapter — `t.me/<bot>?start=iv_<token>` deep links, `/start iv_<token>` extraction                     |
-| `src/runtime/channel-invite-transports/voice.ts`    | Voice transport adapter — code-based redemption metadata                                                        |
-| `src/daemon/guardian-invite-intent.ts`              | Intent detection — routes create/list/revoke requests into the contacts skill                                   |
-| `src/runtime/ingress-service.ts`                    | Shared business logic for invite/member operations (used by both HTTP routes and IPC)                           |
-| `src/runtime/routes/ingress-routes.ts`              | HTTP API handlers for member/invite management including voice invite creation and redemption                   |
-| `src/runtime/routes/inbound-message-handler.ts`     | Invite token intercept in the inbound flow (non-member and inactive-member branches)                            |
-| `src/calls/relay-server.ts`                         | Voice relay state machine — `invite_redemption_pending` subflow (always-on canonical behavior)                  |
-| `src/util/voice-code.ts`                            | Cryptographic voice code generation and SHA-256 hashing                                                         |
-| `src/memory/ingress-invite-store.ts`                | Invite persistence including `findActiveVoiceInvites` for identity-bound lookup                                 |
+| File                                                | Purpose                                                                                                            |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `src/runtime/invite-redemption-service.ts`          | Core redemption engine — token validation, voice code redemption, contact activation, discriminated-union outcomes |
+| `src/runtime/invite-redemption-templates.ts`        | Deterministic reply templates for each redemption outcome                                                          |
+| `src/runtime/channel-invite-transport.ts`           | Transport adapter registry with `buildShareableInvite` / `extractInboundToken` interface                           |
+| `src/runtime/channel-invite-transports/telegram.ts` | Telegram adapter — `t.me/<bot>?start=iv_<token>` deep links, `/start iv_<token>` extraction                        |
+| `src/runtime/channel-invite-transports/voice.ts`    | Voice transport adapter — code-based redemption metadata                                                           |
+| `src/daemon/guardian-invite-intent.ts`              | Intent detection — routes create/list/revoke requests into the contacts skill                                      |
+| `src/runtime/invite-service.ts`                     | Shared business logic for invite operations (used by both HTTP routes and IPC)                                     |
+| `src/runtime/routes/invite-routes.ts`               | HTTP API handlers for invite management including voice invite creation and redemption                             |
+| `src/runtime/routes/inbound-message-handler.ts`     | Invite token intercept in the inbound flow (unknown-contact and inactive-contact branches)                         |
+| `src/calls/relay-server.ts`                         | Voice relay state machine — `invite_redemption_pending` subflow (always-on canonical behavior)                     |
+| `src/util/voice-code.ts`                            | Cryptographic voice code generation and SHA-256 hashing                                                            |
+| `src/memory/invite-store.ts`                        | Invite persistence including `findActiveVoiceInvites` for identity-bound lookup                                    |
 
 ### Voice Inbound Security Model (Canonical)
 
@@ -595,7 +597,7 @@ When no invite exists and no pending guardian challenge is active, the relay ent
 2. On name capture, `notifyGuardianOfAccessRequest` creates a canonical guardian request (`kind: 'access_request'`) and notifies the guardian via the notification pipeline.
 3. The relay transitions to `awaiting_guardian_decision` and plays hold music/messaging while polling the canonical request status.
 4. The guardian approves or denies via any channel (Telegram, SMS, desktop). All decisions route through `applyCanonicalGuardianDecision`, which dispatches to the `access_request` resolver in `guardian-request-resolvers.ts`.
-5. On approval: the resolver directly activates the caller as a trusted contact (upserts member with `status: 'active'`, `policy: 'allow'`), the poll detects the approved status, the relay transitions to the normal call flow with the caller's guardian context updated.
+5. On approval: the resolver directly activates the caller as a trusted contact (sets channel `status: 'active'`, `policy: 'allow'`), the poll detects the approved status, the relay transitions to the normal call flow with the caller's guardian context updated.
 6. On denial or timeout: the caller hears a denial message and the call ends.
 
 **Path 3: Inbound guardian verification (pending challenge)**
@@ -888,7 +890,7 @@ graph LR
         C12["tool_permission_simulate<br/>toolName, input, workingDir?,<br/>isInteractive?, forcePromptSideEffects?,<br/>executionTarget?"]
         C13["conversation_search<br/>query, limit?,<br/>maxMessagesPerConversation?"]
         C14["ingress_invite<br/>create / list / revoke / redeem"]
-        C15["ingress_member<br/>list / upsert / revoke / block"]
+        C15["contacts<br/>list / get / update_channel"]
     end
 
     SOCKET["Unix Socket<br/>~/.vellum/vellum.sock<br/>───────────────<br/>Newline-delimited JSON<br/>Max 96MB per message<br/>Ping/pong every 30s<br/>Auto-reconnect<br/>1s → 30s backoff"]
@@ -920,7 +922,7 @@ graph LR
         S22["tool_permission_simulate_response<br/>decision, riskLevel, reason?,<br/>promptPayload?, matchedRuleId?"]
         S23["conversation_search_response<br/>query, results[]: conversationId,<br/>title, updatedAt, matchingMessages[]"]
         S24["ingress_invite_response<br/>invite / invites"]
-        S25["ingress_member_response<br/>member / members"]
+        S25["contacts_response<br/>contact / contacts"]
     end
 
     C0 --> SOCKET
@@ -2204,8 +2206,8 @@ Connected channels are resolved at signal emission time: vellum is always includ
 | Guardian bindings                            | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; revoked bindings retained                       |
 | Guardian verification challenges             | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; consumed/expired challenges retained            |
 | Guardian approval requests                   | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; decision outcome retained                       |
-| Ingress invites                              | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; token hash stored, raw token never persisted    |
-| Ingress members                              | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; revoked/blocked members retained                |
+| Contact invites                              | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; token hash stored, raw token never persisted    |
+| Contacts & channels                          | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; revoked/blocked contacts retained               |
 | Notification events                          | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; deduplicated by dedupeKey                       |
 | Notification decisions                       | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; FK to notification_events                       |
 | Notification deliveries                      | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; FK to notification_decisions                    |

package/README.md

@@ -337,7 +337,7 @@ Guardian verification and ingress contact management are complementary but indep
 | `src/runtime/trust-context-resolver.ts`         | Actor role classification: guardian / non-guardian / unverified_channel                                               |
 | `src/runtime/routes/inbound-message-handler.ts` | Ingress ACL enforcement, verification-code intercept, escalation creation                                             |
 | `src/contacts/contact-store.ts`                 | Contact + channel CRUD: `findContactChannel`, `upsertContact`, `updateChannelStatus`, `searchContacts`                |
-| `src/memory/ingress-invite-store.ts`            | Invite lifecycle: `createInvite`, `redeemInvite` (atomically creates member record)                                   |
+| `src/memory/invite-store.ts`                    | Invite lifecycle: `createInvite`, `redeemInvite` (atomically creates member record)                                   |
 | `src/memory/channel-guardian-store.ts`          | Persistence for guardian bindings, verification challenges, and approval requests                                     |
 | `src/runtime/guardian-outbound-actions.ts`      | Shared business logic for outbound verification (start/resend/cancel)                                                 |
 | `src/runtime/routes/integration-routes.ts`      | HTTP route handlers for outbound guardian verification endpoints                                                      |
@@ -432,7 +432,7 @@ Redemption auto-creates a **member** record with an access policy:
 - **`deny`** — Messages are rejected with a refusal notice.
 - **`escalate`** — Messages are held for guardian (owner) approval before processing.
 
-Non-members (senders with no invite redemption) are denied by default. Members can be listed, updated, revoked, or blocked via the `ingress_member` IPC contract.
+Non-members (senders with no invite redemption) are denied by default. Contacts can be listed, updated, revoked, or blocked via the HTTP API (`/v1/contacts` and `/v1/contacts/channels`).
 
 ### Escalation Flow
 
@@ -447,15 +447,14 @@ If no guardian binding exists, escalation fails closed — the message is denied
 | Message Type     | Actions                      | Description                                                              |
 | ---------------- | ---------------------------- | ------------------------------------------------------------------------ |
 | `ingress_invite` | create, list, revoke, redeem | Manage invite tokens (SHA-256 hashed, raw token returned once on create) |
-| `ingress_member` | list, upsert, revoke, block  | Manage member records and access policies                                |
 
 ### Key Modules
 
 | File                                                | Purpose                                                                                                          |
 | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `src/memory/ingress-invite-store.ts`                | CRUD for invite tokens with SHA-256 hashing and expiry                                                           |
+| `src/memory/invite-store.ts`                        | CRUD for invite tokens with SHA-256 hashing and expiry                                                           |
 | `src/contacts/contact-store.ts`                     | Contact + channel CRUD with policy enforcement                                                                   |
-| `src/daemon/handlers/config-inbox.ts`               | IPC handlers for ingress invite and member contracts                                                             |
+| `src/daemon/handlers/config-inbox.ts`               | IPC handlers for invite contract                                                                                 |
 | `src/daemon/ipc-contract/inbox.ts`                  | TypeScript type definitions for ingress IPC messages                                                             |
 | `src/runtime/routes/channel-routes.ts`              | ACL enforcement point — member lookup, policy check, escalation creation                                         |
 | `src/runtime/invite-redemption-service.ts`          | Core redemption engine — token validation, member creation, discriminated-union outcomes                         |
@@ -463,7 +462,7 @@ If no guardian binding exists, escalation fails closed — the message is denied
 | `src/runtime/channel-invite-transport.ts`           | Transport adapter registry — `buildShareableInvite` / `extractInboundToken` per channel                          |
 | `src/runtime/channel-invite-transports/telegram.ts` | Telegram adapter — builds `t.me/<bot>?start=iv_<token>` deep links, extracts `iv_` tokens from `/start` commands |
 | `src/daemon/guardian-invite-intent.ts`              | Intent detection — routes guardian invite management requests into the `contacts` skill                          |
-| `src/runtime/ingress-service.ts`                    | Shared business logic for invite/member operations (HTTP + IPC)                                                  |
+| `src/runtime/invite-service.ts`                     | Shared business logic for invite and contact operations (HTTP + IPC)                                             |
 
 ## Database
 

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,74 @@ 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
+      "relationship": "friend",
+      "importance": 0.5,
+      "responseExpectation": null,
+      "preferredTone": 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 +137,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 +257,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.30",
   "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>",
+    );
   });
 });