@vellumai/assistant 0.4.42 → 0.4.44

package/Dockerfile

@@ -97,7 +97,6 @@ USER root
 EXPOSE 3001
 
 ENV RUNTIME_HTTP_PORT=3001
-ENV VELLUM_DAEMON_SOCKET=/home/assistant/.vellum/vellum.sock
 ENV BASE_DATA_DIR=/data
 ENV IS_CONTAINERIZED=true
 

package/README.md

@@ -1,6 +1,6 @@
 # Vellum Assistant Runtime
 
-Bun + TypeScript assistant runtime that owns conversation history, attachment storage, and channel delivery state in a local SQLite database. Exposes a Unix domain socket (macOS) and optional TCP listener (iOS) for native clients, plus an HTTP API consumed by the gateway.
+Bun + TypeScript assistant runtime that owns conversation history, attachment storage, and channel delivery state in a local SQLite database. Exposes an HTTP+SSE API for native clients (macOS, iOS) and the gateway.
 
 ## Architecture
 
@@ -8,10 +8,7 @@ Bun + TypeScript assistant runtime that owns conversation history, attachment st
 CLI / macOS app / iOS app
         │
         ▼
-   Unix socket (~/.vellum/vellum.sock)
-        │
-        ▼
-   DaemonServer (IPC)
+   RuntimeHttpServer (HTTP + SSE)
         │
         ├── Session Manager (in-memory pool, stale eviction)
         │       ├── Anthropic Claude (primary)
@@ -39,21 +36,21 @@ cp .env.example .env
 
 ## Configuration
 
-| Variable               | Required | Default                     | Description                                       |
-| ---------------------- | -------- | --------------------------- | ------------------------------------------------- |
-| `ANTHROPIC_API_KEY`    | Yes      | —                           | Anthropic Claude API key                          |
-| `OPENAI_API_KEY`       | No       | —                           | OpenAI API key                                    |
-| `GEMINI_API_KEY`       | No       | —                           | Google Gemini API key                             |
-| `OLLAMA_API_KEY`       | No       | —                           | API key for authenticated Ollama deployments      |
-| `OLLAMA_BASE_URL`      | No       | `http://127.0.0.1:11434/v1` | Ollama base URL                                   |
-| `RUNTIME_HTTP_PORT`    | No       | —                           | Enable the HTTP server (required for gateway/web) |
-| `VELLUM_DAEMON_SOCKET` | No       | `~/.vellum/vellum.sock`     | Override the assistant socket path                |
+| Variable            | Required | Default                     | Description                                       |
+| ------------------- | -------- | --------------------------- | ------------------------------------------------- |
+| `ANTHROPIC_API_KEY` | Yes      | —                           | Anthropic Claude API key                          |
+| `OPENAI_API_KEY`    | No       | —                           | OpenAI API key                                    |
+| `GEMINI_API_KEY`    | No       | —                           | Google Gemini API key                             |
+| `OLLAMA_API_KEY`    | No       | —                           | API key for authenticated Ollama deployments      |
+| `OLLAMA_BASE_URL`   | No       | `http://127.0.0.1:11434/v1` | Ollama base URL                                   |
+| `RUNTIME_HTTP_PORT` | No       | —                           | Enable the HTTP server (required for gateway/web) |
+| `RUNTIME_HTTP_HOST` | No       | `127.0.0.1`                 | HTTP server bind address                          |
 
 ## Update Bulletin
 
-When a release includes relevant updates, the assistant materializes release notes from the bundled `src/config/templates/UPDATES.md` into `~/.vellum/workspace/UPDATES.md` on startup. The assistant uses judgment to surface updates to the user when relevant, and deletes the file when done.
+When a release includes relevant updates, the assistant materializes release notes from the bundled `src/prompts/templates/UPDATES.md` into `~/.vellum/workspace/UPDATES.md` on startup. The assistant uses judgment to surface updates to the user when relevant, and deletes the file when done.
 
-**For release maintainers:** Update `assistant/src/config/templates/UPDATES.md` with release notes before each relevant release. Leave the template empty (or comment-only) for releases with no user/assistant-facing changes.
+**For release maintainers:** Update `assistant/src/prompts/templates/UPDATES.md` with release notes before each relevant release. Leave the template empty (or comment-only) for releases with no user/assistant-facing changes.
 
 ## Usage
 
@@ -101,7 +98,7 @@ assistant/
 ├── src/
 │   ├── index.ts              # CLI entrypoint (commander)
 │   ├── cli.ts                # Interactive REPL client
-│   ├── daemon/               # Daemon server, IPC protocol, session management
+│   ├── daemon/               # Daemon server, session management
 │   ├── agent/                # Agent loop and LLM interaction
 │   ├── providers/            # LLM provider integrations (Anthropic, OpenAI, Gemini, Ollama)
 │   ├── memory/               # Conversation store, memory indexer, recall (FTS5 + Qdrant)
@@ -115,7 +112,6 @@ assistant/
 │   ├── messaging/            # Message processing pipeline
 │   ├── context/              # Context assembly and compaction
 │   ├── playbooks/            # Channel onboarding playbooks
-│   ├── home-base/            # Home Base app-link bootstrap
 │   ├── hooks/                # Git-style lifecycle hooks
 │   ├── media/                # Media processing and attachments
 │   ├── schedule/             # Reminders and recurrence scheduling (cron + RRULE)
@@ -146,7 +142,7 @@ When the assistant needs tool-use confirmation during a channel session (e.g., T
 
 ### Delivery Semantics
 
-**Single final output guarantee (deliver-once guard):** Both the main poll (`processChannelMessageWithApprovals`) and the post-decision poll (`schedulePostDecisionDelivery`) race to deliver the final assistant reply when a run reaches terminal state. The `claimRunDelivery()` function in `channel-delivery-store.ts` ensures at-most-one delivery per run using an in-memory `Set<string>`. The first caller to claim the run ID proceeds with delivery; the other silently skips. This guard is sufficient because both racing pollers execute within the same process.
+**Single final output guarantee (deliver-once guard):** Both the main poll (`processChannelMessageWithApprovals`) and the post-decision poll (`schedulePostDecisionDelivery`) race to deliver the final assistant reply when a run reaches terminal state. The `claimRunDelivery()` function in `delivery-channels.ts` ensures at-most-one delivery per run using an in-memory `Set<string>`. The first caller to claim the run ID proceeds with delivery; the other silently skips. This guard is sufficient because both racing pollers execute within the same process.
 
 **Stale callback blocking:** When inbound callback data (e.g., a Telegram button press) does not match any pending approval, the runtime returns `stale_ignored` and does not process the payload as a regular message. This prevents stale button presses from old approval prompts from triggering unrelated agent loops.
 
@@ -160,18 +156,17 @@ All approval prompt delivery paths use a **fail-closed** policy -- if the prompt
 
 ### Plain-Text Fallback for Non-Rich Channels
 
-Channels that do not support rich inline approval UI (e.g., inline keyboards) receive plain-text instructions embedded in the message body. The `channelSupportsRichApprovalUI()` check determines whether to send the structured `promptText` (for rich channels like Telegram) or the `plainTextFallback` string (for all other channels, e.g., SMS). The fallback text includes instructions like "Reply yes/no/always" so the user can respond via text.
+Channels that do not support rich inline approval UI (e.g., inline keyboards) receive plain-text instructions embedded in the message body. The `channelSupportsRichApprovalUI()` check determines whether to send the structured `promptText` (for rich channels like Telegram) or the `plainTextFallback` string (for all other channels). The fallback text includes instructions so the user can respond via text; the conversational approval engine then classifies the free-text response.
 
 ### Key modules
 
-| File                                     | Purpose                                                                                                                           |
-| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `src/runtime/channel-approvals.ts`       | Orchestration: `getChannelApprovalPrompt`, `buildApprovalUIMetadata`, `handleChannelDecision`, `buildReminderPrompt`              |
-| `src/runtime/channel-approval-parser.ts` | Plain-text decision parser — matches phrases like `yes`, `approve`, `always`, `no`, `reject`, `deny`, `cancel` (case-insensitive) |
-| `src/runtime/channel-approval-types.ts`  | Shared types: `ApprovalAction`, `ChannelApprovalPrompt`, `ApprovalUIMetadata`, `ApprovalDecisionResult`                           |
-| `src/runtime/routes/channel-routes.ts`   | Integration point: `handleApprovalInterception` and `processChannelMessageWithApprovals` in the channel inbound handler           |
-| `src/runtime/gateway-client.ts`          | `deliverApprovalPrompt()` — sends the approval payload (text + UI metadata) to the gateway for rendering                          |
-| `src/memory/runs-store.ts`               | `getPendingConfirmationsByConversation` — queries runs in `needs_confirmation` state                                              |
+| File                                    | Purpose                                                                                                                 |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `src/runtime/channel-approvals.ts`      | Orchestration: `getChannelApprovalPrompt`, `buildApprovalUIMetadata`, `handleChannelDecision`, `buildReminderPrompt`    |
+| `src/runtime/channel-approval-types.ts` | Shared types: `ApprovalAction`, `ChannelApprovalPrompt`, `ApprovalUIMetadata`, `ApprovalDecisionResult`                 |
+| `src/runtime/routes/channel-routes.ts`  | Integration point: `handleApprovalInterception` and `processChannelMessageWithApprovals` in the channel inbound handler |
+| `src/runtime/gateway-client.ts`         | `deliverApprovalPrompt()` — sends the approval payload (text + UI metadata) to the gateway for rendering                |
+| `src/memory/runs-store.ts`              | `getPendingConfirmationsByConversation` — queries runs in `needs_confirmation` state                                    |
 
 ### Enabling
 
@@ -191,7 +186,7 @@ Guardian actor-role _classification_ (determining whether a sender is guardian,
 
 ### Ingress Boundary Guarantees (Gateway-Only Mode)
 
-The runtime operates in **gateway-only mode**: all public-facing webhook paths are blocked at the runtime level. Direct access to Twilio webhook routes (`/webhooks/twilio/voice`, `/webhooks/twilio/status`, `/webhooks/twilio/connect-action`, `/webhooks/twilio/sms`) and their legacy equivalents (`/v1/calls/twilio/*`) returns `410 GATEWAY_ONLY`. This ensures external webhook traffic (including SMS) can only reach the runtime through the gateway, which performs signature validation before forwarding.
+The runtime operates in **gateway-only mode**: all public-facing webhook paths are blocked at the runtime level. Direct access to Twilio webhook routes (`/webhooks/twilio/voice`, `/webhooks/twilio/status`, `/webhooks/twilio/connect-action`) and their legacy equivalents (`/v1/calls/twilio/*`) returns `410 GATEWAY_ONLY`. This ensures external webhook traffic can only reach the runtime through the gateway, which performs signature validation before forwarding.
 
 Internal forwarding routes (`/v1/internal/twilio/*`) are unaffected — these accept pre-validated payloads from the gateway over the private network.
 
@@ -204,49 +199,43 @@ The `/channels/inbound` endpoint requires a JWT with the `svc_gateway` principal
 
 ## Twilio Setup Primitive
 
-Twilio is the shared telephony provider for both voice calls and SMS messaging. Configuration is managed through HTTP control-plane endpoints exposed by the runtime and proxied by the gateway. For SMS-specific onboarding (including compliance verification and test sending), the `sms-setup` skill provides a guided conversational flow that layers on top of `twilio-setup`.
+Twilio is the telephony provider for voice calls. Configuration is managed through HTTP control-plane endpoints exposed by the runtime and proxied by the gateway.
 
 ### Twilio HTTP Control-Plane Endpoints
 
-The runtime exposes a RESTful HTTP API for Twilio configuration, credential management, phone number operations, and SMS compliance:
-
-| Method | Path                                                   | Description                                                                                                                                                     |
-| ------ | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| GET    | `/v1/integrations/twilio/config`                       | Returns current state: `hasCredentials` (boolean) and `phoneNumber` (if assigned)                                                                               |
-| POST   | `/v1/integrations/twilio/credentials`                  | Validates and stores Account SID and Auth Token in secure storage (Keychain / encrypted file)                                                                   |
-| DELETE | `/v1/integrations/twilio/credentials`                  | Removes stored credentials. Preserves the phone number in both config and secure key so re-entering credentials resumes working without reassigning the number. |
-| GET    | `/v1/integrations/twilio/numbers`                      | Lists all incoming phone numbers on the Twilio account with their capabilities (voice, SMS)                                                                     |
-| POST   | `/v1/integrations/twilio/numbers/provision`            | Purchases a new phone number. Accepts optional `areaCode` and `country`. Auto-assigns and configures webhooks when ingress is available.                        |
-| POST   | `/v1/integrations/twilio/numbers/assign`               | Assigns an existing Twilio phone number (E.164) and auto-configures webhooks when ingress is available                                                          |
-| POST   | `/v1/integrations/twilio/numbers/release`              | Releases a phone number from the Twilio account and clears local references                                                                                     |
-| GET    | `/v1/integrations/twilio/sms/compliance`               | Returns SMS compliance posture: number type (toll-free vs 10DLC) and toll-free verification status                                                              |
-| POST   | `/v1/integrations/twilio/sms/compliance/tollfree`      | Submits a new toll-free verification request                                                                                                                    |
-| PATCH  | `/v1/integrations/twilio/sms/compliance/tollfree/:sid` | Updates an existing toll-free verification by SID                                                                                                               |
-| DELETE | `/v1/integrations/twilio/sms/compliance/tollfree/:sid` | Deletes a toll-free verification by SID                                                                                                                         |
-| POST   | `/v1/integrations/twilio/sms/test`                     | Sends a test SMS and polls for delivery status                                                                                                                  |
-| POST   | `/v1/integrations/twilio/sms/doctor`                   | Runs comprehensive SMS health diagnostics                                                                                                                       |
+The runtime exposes a RESTful HTTP API for Twilio configuration, credential management, and phone number operations:
+
+| Method | Path                                        | Description                                                                                                                                 |
+| ------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| GET    | `/v1/integrations/twilio/config`            | Returns current state: `hasCredentials` (boolean) and `phoneNumber` (if assigned)                                                           |
+| POST   | `/v1/integrations/twilio/credentials`       | Validates and stores Account SID and Auth Token in secure storage (Keychain / encrypted file)                                               |
+| DELETE | `/v1/integrations/twilio/credentials`       | Removes stored credentials. Preserves the phone number in config so re-entering credentials resumes working without reassigning the number. |
+| GET    | `/v1/integrations/twilio/numbers`           | Lists all incoming phone numbers on the Twilio account with their capabilities                                                              |
+| POST   | `/v1/integrations/twilio/numbers/provision` | Purchases a new phone number. Accepts optional `areaCode` and `country`. Auto-assigns and configures webhooks when ingress is available.    |
+| POST   | `/v1/integrations/twilio/numbers/assign`    | Assigns an existing Twilio phone number (E.164) and auto-configures webhooks when ingress is available                                      |
+| POST   | `/v1/integrations/twilio/numbers/release`   | Releases a phone number from the Twilio account and clears local references                                                                 |
 
 All endpoints are JWT-authenticated (require a valid JWT with appropriate scopes). Skills and clients should call the gateway URL (default `http://localhost:7830`) rather than the runtime port directly, as the gateway proxies all `/v1/integrations/twilio/*` routes.
 
 ### Ingress Webhook Reconciliation
 
-When the public ingress URL is changed via the Settings UI (`ingress_config` set action), the assistant automatically reconciles Twilio webhooks in addition to triggering a Telegram webhook reconcile on the gateway. If all of the following conditions are met, the assistant pushes updated webhook URLs (voice, status callback, SMS) to Twilio:
+When the public ingress URL is changed via the Settings UI (`ingress_config` set action), the assistant automatically reconciles Twilio webhooks in addition to triggering a Telegram webhook reconcile on the gateway. If all of the following conditions are met, the assistant pushes updated webhook URLs (voice, status callback) to Twilio:
 
 1. Ingress is being **enabled** (not disabled)
 2. Twilio **credentials** are configured (Account SID + Auth Token in secure storage)
-3. A phone number is **assigned** (persisted in `sms.phoneNumber` config)
+3. A phone number is **assigned** (persisted in `twilio.phoneNumber` config)
 
 This reconciliation is **best-effort and fire-and-forget** -- failures are logged but do not block the ingress config save or produce an error response. This ensures that changing a tunnel URL (e.g., restarting ngrok) automatically updates Twilio's webhook routing without requiring manual re-assignment of the phone number.
 
 ### Single-Number-Per-Assistant Model
 
-Each assistant is assigned a single Twilio phone number that is shared between voice calls and SMS. The number is stored in the assistant's config at `sms.phoneNumber` (legacy global field) and used as the `From` for outbound SMS via the gateway's `/deliver/sms` endpoint. The same credentials (Account SID, Auth Token) are used for both voice and SMS operations.
+Each assistant is assigned a single Twilio phone number used for voice calls. The number is stored in the assistant's config at `twilio.phoneNumber`.
 
 #### Assistant-Scoped Phone Numbers
 
-When `assistantId` is provided in the Twilio control-plane request, the provision and assign endpoints persist the phone number into a per-assistant mapping at `sms.assistantPhoneNumbers` (a `Record<string, string>` keyed by assistant ID). The legacy `sms.phoneNumber` field is always updated for backward compatibility.
+When `assistantId` is provided in the Twilio control-plane request, the provision and assign endpoints persist the phone number into a per-assistant mapping at `twilio.assistantPhoneNumbers` (a `Record<string, string>` keyed by assistant ID). The `twilio.phoneNumber` field is always updated as well.
 
-The config endpoint (`GET /v1/integrations/twilio/config`), when called with `assistantId`, resolves the phone number by checking `sms.assistantPhoneNumbers[assistantId]` first, falling back to `sms.phoneNumber`. This allows multiple assistants to have distinct phone numbers while preserving existing behavior for single-assistant setups.
+The config endpoint (`GET /v1/integrations/twilio/config`), when called with `assistantId`, resolves the phone number by checking `twilio.assistantPhoneNumbers[assistantId]` first, falling back to `twilio.phoneNumber`. This allows multiple assistants to have distinct phone numbers while preserving existing behavior for single-assistant setups.
 
 The per-assistant mapping is propagated to the gateway via the config file watcher, enabling phone-number-based routing at the gateway boundary (see Gateway README).
 
@@ -255,18 +244,17 @@ The per-assistant mapping is propagated to the gateway via the config file watch
 At runtime, `getTwilioConfig()` resolves the phone number using this priority chain:
 
 1. **`TWILIO_PHONE_NUMBER` env var** — highest priority, explicit override for dev/CI.
-2. **`sms.phoneNumber` in config** — the primary source of truth, written by `provision_number` and `assign_number`.
-3. **`credential:twilio:phone_number` secure key** — backward-compatible fallback for setups that predate the config-first model.
+2. **`twilio.phoneNumber` in config** — the primary source of truth, written by `provision_number` and `assign_number`.
 
-If no number is found after all three sources, an error is thrown.
+If no number is found after both sources, an error is thrown.
 
 ### Assistant-Scoped Guardian State
 
-Guardian bindings, verification challenges, and approval requests are all scoped to an `(assistantId, channel)` pair. The `assistantId` parameter flows through `handleChannelInbound`, `validateAndConsumeChallenge`, `isGuardian`, `getGuardianBinding`, and `createApprovalRequest`. This means each assistant has its own independent guardian binding per channel -- verifying as guardian on one assistant does not grant guardian status on another.
+Guardian bindings, verification challenges, and approval requests are all scoped to an `(assistantId, channel)` pair. The `assistantId` parameter flows through `handleChannelInbound`, `validateAndConsumeVerification`, `isGuardian`, `getGuardianBinding`, and `createApprovalRequest`. This means each assistant has its own independent guardian binding per channel -- verifying as guardian on one assistant does not grant guardian status on another.
 
 ### Channel-Aware Guardian Challenges
 
-The channel guardian service generates verification challenge instructions with channel-appropriate wording. The `channelLabel()` function maps `sourceChannel` values to human-readable labels (e.g., `"telegram"` -> `"Telegram"`, `"sms"` -> `"SMS"`), so challenge prompts reference the correct channel name.
+The channel guardian service generates verification challenge instructions with channel-appropriate wording. The `channelLabel()` function maps `sourceChannel` values to human-readable labels (e.g., `"telegram"` -> `"Telegram"`, `"phone"` -> `"Phone"`), so challenge prompts reference the correct channel name.
 
 ### Operator Notes
 
@@ -276,11 +264,11 @@ The channel guardian service generates verification challenge instructions with
 
 ### Vellum Guardian Identity (Actor Tokens)
 
-The vellum channel (macOS, iOS, CLI) uses JWTs to bind guardian identity to HTTP requests. This enables identity-based authentication for the local desktop/mobile channel, paralleling how external channels (Telegram, SMS) use `actorExternalId` for guardian identity.
+The vellum channel (macOS, iOS) uses JWTs to bind guardian identity to HTTP requests. This enables identity-based authentication for the local desktop/mobile channel, paralleling how external channels (Telegram) use `actorExternalId` for guardian identity. The CLI authenticates using its bearer token obtained during `hatch`.
 
-- **Bootstrap**: After hatch, the macOS client calls `POST /v1/integrations/guardian/vellum/bootstrap` with `{ platform, deviceId }`. Returns `{ guardianPrincipalId, accessToken, accessTokenExpiresAt, refreshToken, refreshTokenExpiresAt, refreshAfter, isNew }`. The endpoint is idempotent -- repeated calls with the same device return the same principal but mint fresh credentials.
+- **Bootstrap**: After hatch, the macOS client calls `POST /v1/guardian/init` with `{ platform, deviceId }`. Returns `{ guardianPrincipalId, accessToken, accessTokenExpiresAt, refreshToken, refreshTokenExpiresAt, refreshAfter, isNew }`. The endpoint is idempotent -- repeated calls with the same device return the same principal but mint fresh credentials. The CLI does not bootstrap separately; it uses the bearer token minted during `hatch`.
 - **iOS pairing**: The pairing response includes `accessToken` and `refreshToken` credentials automatically when a vellum guardian binding exists.
-- **IPC fallback**: Local IPC (Unix socket) connections resolve identity server-side via `resolveLocalIpcGuardianContext()` without requiring a JWT.
+- **Local identity**: Local connections resolve identity server-side via `resolveLocalGuardianContext()` without requiring a JWT.
 - **HTTP enforcement**: All vellum HTTP routes require a valid JWT via the `Authorization: Bearer <jwt>` header. The JWT carries identity claims (`sub` with principal type and ID) and scope permissions. Route-level enforcement in `route-policy.ts` checks scopes and principal types.
 - **Startup migration**: On assistant start, `ensureVellumGuardianBinding()` backfills a vellum guardian binding for existing installations so the identity system works without requiring a manual bootstrap step.
 
@@ -292,8 +280,8 @@ This section documents the end-to-end flow from guardian verification through in
 
 Guardian verification establishes a cryptographic trust binding between a human identity and an `(assistantId, channel)` pair. The flow is:
 
-1. **Challenge creation** — The owner initiates verification from the desktop UI, which sends a guardian-verification IPC message (`create_challenge` action) to the assistant. The assistant generates a random secret (32-byte hex for unbound inbound/bootstrap sessions, 6-digit numeric for identity-bound sessions), hashes it with SHA-256, stores the hash with a 10-minute TTL, and returns the raw secret to the desktop.
-2. **Code sharing** — The desktop displays the code and instructs the owner to reply with that code in the target channel conversation (e.g., Telegram or SMS).
+1. **Challenge creation** — The owner initiates verification from the desktop UI, which sends a channel_verification_session request (`create_session` action) to the assistant. The assistant generates a random secret (32-byte hex for unbound inbound/bootstrap sessions, 6-digit numeric for identity-bound sessions), hashes it with SHA-256, stores the hash with a 10-minute TTL, and returns the raw secret to the desktop.
+2. **Code sharing** — The desktop displays the code and instructs the owner to reply with that code in the target channel conversation (e.g., Telegram).
 3. **Verification** — When the message arrives at `/channels/inbound`, the handler intercepts valid verification-code replies before normal message processing. It hashes the provided code, looks up a matching pending challenge, validates expiry, and consumes the challenge (preventing replay).
 4. **Binding** — On success, any existing active binding for the `(assistantId, channel)` pair is revoked, and a new guardian binding is created with the verifier's `actorExternalId` and `chatId` (DB columns: `externalUserId`, `chatId`). The verifier receives a confirmation message.
 
@@ -318,7 +306,7 @@ When a member's policy is `escalate`:
 1. The handler looks up the guardian binding for the `(assistantId, channel)` pair. If no binding exists, the message is denied with `escalate_no_guardian` (fail-closed).
 2. The raw message payload is stored so it can be recovered on approval.
 3. A `channel_guardian_approval_request` is created with a 30-minute TTL.
-4. The guardian is notified via the canonical notification pipeline (`emitNotificationSignal`), which routes the escalation alert to all configured channels (Telegram/SMS push, desktop notification).
+4. The guardian is notified via the canonical notification pipeline (`emitNotificationSignal`), which routes the escalation alert to all configured channels (Telegram push, desktop notification).
 5. On **approve**, the stored payload is replayed through the agent pipeline and the assistant's response is delivered to the external user. On **deny**, a refusal message is sent.
 
 ### How the Systems Connect
@@ -331,41 +319,44 @@ Guardian verification and ingress contact management are complementary but indep
 
 ### Key Modules
 
-| File                                            | Purpose                                                                                                               |
-| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `src/runtime/channel-guardian-service.ts`       | Challenge lifecycle: `createVerificationChallenge`, `validateAndConsumeChallenge`, `getGuardianBinding`, `isGuardian` |
-| `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/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                                                      |
+| File                                                | Purpose                                                                                                                          |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `src/runtime/channel-verification-service.ts`       | Verification lifecycle: `createInboundVerificationSession`, `validateAndConsumeVerification`, `getGuardianBinding`, `isGuardian` |
+| `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/invite-store.ts`                        | Invite lifecycle: `createInvite`, `redeemInvite` (atomically creates member record)                                              |
+| `src/memory/channel-verification-sessions.ts`       | Guardian binding types and verification challenge persistence                                                                    |
+| `src/memory/guardian-approvals.ts`                  | Approval request persistence                                                                                                     |
+| `src/runtime/verification-outbound-actions.ts`      | Shared business logic for outbound verification (start/resend/cancel)                                                            |
+| `src/runtime/routes/channel-verification-routes.ts` | HTTP route handlers for outbound guardian verification endpoints                                                                 |
 
 ### Chat-Initiated Guardian Verification
 
 Guardian verification can also be initiated through normal desktop chat. When the user asks the assistant to set up guardian verification, the conversational routing layer loads the `guardian-verify-setup` skill, which guides the flow:
 
-1. Confirm which channel to verify (SMS, voice, or Telegram).
+1. Confirm which channel to verify (voice or Telegram).
 2. Collect the destination (phone number or Telegram handle/chat ID).
 3. Call the outbound HTTP endpoints to start, resend, or cancel verification.
 4. Guide the user through the verification lifecycle conversationally.
 
 **Outbound HTTP Endpoints** (exposed via the gateway API and forwarded to the runtime):
 
-| Endpoint                                    | Method | Description                                                                           |
-| ------------------------------------------- | ------ | ------------------------------------------------------------------------------------- |
-| `/v1/integrations/guardian/outbound/start`  | POST   | Start outbound verification. Body: `{ channel, destination?, assistantId?, rebind? }` |
-| `/v1/integrations/guardian/outbound/resend` | POST   | Resend verification code. Body: `{ channel, assistantId? }`                           |
-| `/v1/integrations/guardian/outbound/cancel` | POST   | Cancel active session. Body: `{ channel, assistantId? }`                              |
+| Endpoint                                   | Method | Description                                                                                                                                                                                                                                       |
+| ------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/v1/channel-verification-sessions`        | POST   | Create a verification session. Supports guardian (default), outbound (with `destination`), and trusted contact (with `purpose: "trusted_contact"` + `contactChannelId`). Body: `{ channel?, destination?, rebind?, purpose?, contactChannelId? }` |
+| `/v1/channel-verification-sessions/resend` | POST   | Resend verification code for an active outbound session. Body: `{ channel }`                                                                                                                                                                      |
+| `/v1/channel-verification-sessions`        | DELETE | Cancel all active sessions (inbound + outbound) for a channel. Body: `{ channel }`                                                                                                                                                                |
+| `/v1/channel-verification-sessions/revoke` | POST   | Cancel all active sessions and revoke the guardian binding. Body: `{ channel? }`                                                                                                                                                                  |
+| `/v1/channel-verification-sessions/status` | GET    | Check guardian binding status. Query: `?channel=<channel>`                                                                                                                                                                                        |
 
-These endpoints share the same business logic as the IPC-based verification flow via `guardian-outbound-actions.ts`. Skills and clients should call the gateway URL (default `http://localhost:7830`) rather than the runtime port directly.
+These endpoints share the same business logic as the IPC-based verification flow via `verification-outbound-actions.ts`. Skills and clients should call the gateway URL (default `http://localhost:7830`) rather than the runtime port directly.
 
 **Security constraint:** Guardian verification control-plane endpoints are restricted to guardian and desktop (trusted) actors only. Non-guardian and unverified-channel actors cannot invoke these endpoints conversationally via tools. Attempts are denied with a message explaining that guardian verification actions are restricted to guardian users.
 
 ## Channel Readiness
 
-Channel readiness is exposed via HTTP control-plane endpoints that provide a unified way to check whether a channel (SMS, Telegram, etc.) is fully configured and operational. Local checks (credential presence, phone number assignment, ingress config) run synchronously; remote checks (API reachability) run by default and are cached with a 5-minute TTL. Remote checks can be disabled by passing `includeRemote=false`.
+Channel readiness is exposed via HTTP control-plane endpoints that provide a unified way to check whether a channel (Telegram, Voice, etc.) is fully configured and operational. Local checks (credential presence, phone number assignment, ingress config) run synchronously; remote checks (API reachability) run by default and are cached with a 5-minute TTL. Remote checks can be disabled by passing `includeRemote=false`.
 
 ### Channel Readiness HTTP Endpoints
 
@@ -378,7 +369,6 @@ All endpoints are bearer-authenticated. Skills and clients should call the gatew
 
 ### Built-in Channel Probes
 
-- **SMS**: Checks Twilio credentials, phone number assignment, and public ingress URL.
 - **Voice**: Checks Twilio credentials, phone number assignment, and public ingress URL.
 - **Telegram**: Checks bot token, webhook secret, and public ingress URL.
 - **Email**: Checks AgentMail API key, invite policy, public ingress URL, and verifies an inbox address is available (remote check).
@@ -395,13 +385,13 @@ All endpoints are bearer-authenticated. Skills and clients should call the gatew
 
 ## Ingress Membership + Escalation
 
-Secure cross-user messaging allows external users (non-guardians) to interact with the assistant through channels (Telegram, SMS) under the owner's control. Access is governed by an invite-based membership system with per-member policy enforcement.
+Secure cross-user messaging allows external users (non-guardians) to interact with the assistant through channels (Telegram) under the owner's control. Access is governed by an invite-based membership system with per-member policy enforcement.
 
 ### Ingress Membership
 
 External users join through **invite tokens**. There are two invite flows:
 
-1. **IPC-based (legacy)** — The owner creates an invite via IPC, obtains the raw token, and shares it manually. The external user redeems the token by sending it as a channel message.
+1. **Manual** — The owner creates an invite via the HTTP API, obtains the raw token, and shares it manually. The external user redeems the token by sending it as a channel message.
 2. **Guardian-initiated invite links (Telegram)** — The guardian asks the assistant to create an invite link via desktop chat. The assistant creates an invite, builds a channel-specific deep link, and presents it for sharing. The invitee clicks the link and is automatically granted access.
 
 #### Guardian-Initiated Invite Link Flow (Telegram)
@@ -419,7 +409,7 @@ The `iv_` prefix distinguishes invite tokens from `gv_` (guardian verification)
 The invite redemption system uses a three-layer architecture:
 
 - **Core redemption engine** (`invite-redemption-service.ts`) — Channel-agnostic business logic that validates tokens, enforces expiry/use-count/channel-match constraints, handles member reactivation, and returns a discriminated-union `InviteRedemptionOutcome`. Deterministic reply templates (`invite-redemption-templates.ts`) map each outcome to a user-facing message without passing through the LLM.
-- **Channel transport adapters** (`channel-invite-transport.ts` + `channel-invite-transports/`) — A registry of per-channel adapters that know how to build shareable links (`buildShareLink`) and extract inbound tokens (`extractInboundToken`). Adapters are implemented for Telegram, SMS, Voice, Email, WhatsApp, and Slack.
+- **Channel transport adapters** (`channel-invite-transport.ts` + `channel-invite-transports/`) — A registry of per-channel adapters that know how to build shareable links (`buildShareLink`) and extract inbound tokens (`extractInboundToken`). Adapters are implemented for Telegram, Voice, Email, WhatsApp, and Slack.
 - **Conversational orchestration** (`guardian-invite-intent.ts`) — Pattern-based intent detection that intercepts guardian invite management requests (create, list, revoke) in the session pipeline and forces immediate entry into the `contacts` skill, bypassing the normal agent loop.
 
 Redemption auto-creates a **member** record with an access policy:
@@ -432,15 +422,15 @@ Non-members (senders with no invite redemption) are denied by default. Contacts
 
 ### Escalation Flow
 
-When a member's policy is `escalate`, inbound messages create a `channel_guardian_approval_request` and the guardian is notified through the canonical notification pipeline (`emitNotificationSignal`). The pipeline routes the escalation alert to all configured channels (Telegram/SMS push, desktop notification).
+When a member's policy is `escalate`, inbound messages create a `channel_guardian_approval_request` and the guardian is notified through the canonical notification pipeline (`emitNotificationSignal`). The pipeline routes the escalation alert to all configured channels (Telegram push, desktop notification).
 
 On **approve**: the original message payload is recovered from the channel delivery store and processed through the agent pipeline. The assistant's reply is delivered back to the external user via the gateway. On **deny**: a refusal message is sent to the external user.
 
 If no guardian binding exists, escalation fails closed — the message is denied rather than left in a silent wait state.
 
-### IPC Contracts
+### HTTP API
 
-| Message Type     | Actions                      | Description                                                              |
+| Endpoint         | Actions                      | Description                                                              |
 | ---------------- | ---------------------------- | ------------------------------------------------------------------------ |
 | `ingress_invite` | create, list, revoke, redeem | Manage invite tokens (SHA-256 hashed, raw token returned once on create) |
 
@@ -450,21 +440,20 @@ If no guardian binding exists, escalation fails closed — the message is denied
 | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
 | `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 invite contract                                                                                 |
-| `src/daemon/ipc-contract/inbox.ts`                  | TypeScript type definitions for ingress IPC messages                                                             |
+| `src/daemon/handlers/config-inbox.ts`               | HTTP handlers for invite operations                                                                              |
 | `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                         |
 | `src/runtime/invite-redemption-templates.ts`        | Deterministic reply templates for each redemption outcome                                                        |
 | `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/invite-service.ts`                     | Shared business logic for invite and contact operations (HTTP + IPC)                                             |
+| `src/runtime/invite-service.ts`                     | Shared business logic for invite and contact operations                                                          |
 
 ## Database
 
 SQLite via Drizzle ORM, stored at `~/.vellum/workspace/data/db/assistant.db`. Key tables include conversations, messages, tool invocations, attachments, memory segments (with FTS5), memory items, entities, reminders, and recurrence schedules (cron + RRULE).
 
-> **Compatibility note:** The recurrence schedule system supports both cron expressions and iCalendar RRULE syntax. The legacy field names `cron_expression` and `cronExpression` remain supported in API inputs. New code should use the `expression` field with an explicit `syntax` discriminator. See [`docs/architecture/scheduling.md`](docs/architecture/scheduling.md) for details.
+> **Note:** The recurrence schedule system supports both cron expressions and iCalendar RRULE syntax. Use the `expression` field with an explicit `syntax` discriminator. See [`docs/architecture/scheduling.md`](docs/architecture/scheduling.md) for details.
 
 Run migrations:
 

package/bun.lock

@@ -8,6 +8,7 @@
         "@anthropic-ai/claude-agent-sdk": "^0.2.42",
         "@anthropic-ai/sdk": "^0.39.0",
         "@google/genai": "^1.40.0",
+        "@hono/node-server": "^1.19.11",
         "@modelcontextprotocol/sdk": "^1.15.1",
         "@qdrant/js-client-rest": "^1.16.2",
         "@sentry/node": "^10.38.0",
@@ -18,6 +19,7 @@
         "dotenv": "^17.3.1",
         "drizzle-orm": "^0.38.4",
         "esbuild": "^0.24.0",
+        "hono": "^4.12.5",
         "ink": "^6.7.0",
         "jszip": "^3.10.1",
         "minimatch": "^10.2.4",
@@ -153,7 +155,7 @@
 
     "@grpc/proto-loader": ["@grpc/proto-loader@0.8.0", "", { "dependencies": { "lodash.camelcase": "^4.3.0", "long": "^5.0.0", "protobufjs": "^7.5.3", "yargs": "^17.7.2" }, "bin": { "proto-loader-gen-types": "build/bin/proto-loader-gen-types.js" } }, "sha512-rc1hOQtjIWGxcxpb9aHAfLpIctjEnsDehj0DAiVfBlmT84uvR0uUtN2hEi/ecvWVjXUGf5qPF4qEgiLOx1YIMQ=="],
 
-    "@hono/node-server": ["@hono/node-server@1.19.9", "", { "peerDependencies": { "hono": "^4" } }, "sha512-vHL6w3ecZsky+8P5MD+eFfaGTyCeOHUIFYMGpQGbrBTSmNNoxv0if69rEZ5giu36weC5saFuznL411gRX7bJDw=="],
+    "@hono/node-server": ["@hono/node-server@1.19.11", "", { "peerDependencies": { "hono": "^4" } }, "sha512-dr8/3zEaB+p0D2n/IUrlPF1HZm586qgJNXK1a9fhg/PzdtkK7Ksd5l312tJX2yBuALqDYBlG20QEbayqPyxn+g=="],
 
     "@humanfs/core": ["@humanfs/core@0.19.1", "", {}, "sha512-5DyQ4+1JEUzejeK1JGICcideyfUbGixgS9jNgex5nqkW+cY7WZhxBigmieN5Qnw9ZosSNVC9KQKyb+GUaGyKUA=="],
 
@@ -859,7 +861,7 @@
 
     "help-me": ["help-me@5.0.0", "", {}, "sha512-7xgomUX6ADmcYzFik0HzAxh/73YlKR9bmFzf51CZwR+b6YtzU2m0u49hQCqV6SvlqIqsaxovfwdvbnsw3b/zpg=="],
 
-    "hono": ["hono@4.12.3", "", {}, "sha512-SFsVSjp8sj5UumXOOFlkZOG6XS9SJDKw0TbwFeV+AJ8xlST8kxK5Z/5EYa111UY8732lK2S/xB653ceuaoGwpg=="],
+    "hono": ["hono@4.12.5", "", {}, "sha512-3qq+FUBtlTHhtYxbxheZgY8NIFnkkC/MR8u5TTsr7YZ3wixryQ3cCwn3iZbg8p8B88iDBBAYSfZDS75t8MN7Vg=="],
 
     "http-errors": ["http-errors@2.0.1", "", { "dependencies": { "depd": "~2.0.0", "inherits": "~2.0.4", "setprototypeof": "~1.2.0", "statuses": "~2.0.2", "toidentifier": "~1.0.1" } }, "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ=="],
 
@@ -1357,8 +1359,12 @@
 
     "@isaacs/cliui/wrap-ansi": ["wrap-ansi@8.1.0", "", { "dependencies": { "ansi-styles": "^6.1.0", "string-width": "^5.0.1", "strip-ansi": "^7.0.1" } }, "sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ=="],
 
+    "@modelcontextprotocol/sdk/@hono/node-server": ["@hono/node-server@1.19.9", "", { "peerDependencies": { "hono": "^4" } }, "sha512-vHL6w3ecZsky+8P5MD+eFfaGTyCeOHUIFYMGpQGbrBTSmNNoxv0if69rEZ5giu36weC5saFuznL411gRX7bJDw=="],
+
     "@modelcontextprotocol/sdk/ajv": ["ajv@8.18.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A=="],
 
+    "@modelcontextprotocol/sdk/hono": ["hono@4.12.3", "", {}, "sha512-SFsVSjp8sj5UumXOOFlkZOG6XS9SJDKw0TbwFeV+AJ8xlST8kxK5Z/5EYa111UY8732lK2S/xB653ceuaoGwpg=="],
+
     "@opentelemetry/auto-instrumentations-node/@opentelemetry/instrumentation": ["@opentelemetry/instrumentation@0.210.0", "", { "dependencies": { "@opentelemetry/api-logs": "0.210.0", "import-in-the-middle": "^2.0.0", "require-in-the-middle": "^8.0.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-sLMhyHmW9katVaLUOKpfCnxSGhZq2t1ReWgwsu2cSgxmDVMB690H9TanuexanpFI94PJaokrqbp8u9KYZDUT5g=="],
 
     "@opentelemetry/auto-instrumentations-node/@opentelemetry/instrumentation-amqplib": ["@opentelemetry/instrumentation-amqplib@0.57.0", "", { "dependencies": { "@opentelemetry/core": "^2.0.0", "@opentelemetry/instrumentation": "^0.210.0", "@opentelemetry/semantic-conventions": "^1.33.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-hgHnbcopDXju7164mwZu7+6mLT/+O+6MsyedekrXL+HQAYenMqeG7cmUOE0vI6s/9nW08EGHXpD+Q9GhLU1smA=="],