@vellumai/assistant 0.3.5 → 0.3.7

package/README.md

@@ -286,6 +286,57 @@ Response type: `channel_readiness_response` with `success`, optional `snapshots`
 | `src/runtime/channel-readiness-service.ts` | Service class with probe registration, cached readiness evaluation, and built-in SMS/Telegram probes |
 | `src/daemon/handlers/config.ts` | `handleChannelReadiness` — IPC handler for `channel_readiness` messages |
 
+## Assistant Inbox (Ingress Membership + Escalation)
+
+The assistant inbox provides secure cross-user messaging, allowing 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.
+
+### Ingress Membership
+
+External users join through **invite tokens** — the owner creates an invite via the desktop UI or IPC, and the external user redeems the token by sending it as a channel message. Redemption auto-creates a **member** record with an access policy:
+
+- **`allow`** — Messages are processed normally through the agent pipeline.
+- **`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.
+
+### Escalation Flow (Dual-Surface)
+
+When a member's policy is `escalate`, inbound messages create a `channel_guardian_approval_request` and notify the guardian through two surfaces:
+
+1. **Channel push notification** — The guardian receives a message on their configured channel (Telegram/SMS) describing the escalation, allowing quick approve/deny from their phone.
+2. **Desktop inbox UI** — The macOS `AssistantInboxPanel` shows pending escalations with approve/deny buttons in the Escalations tab. A 15-second polling loop keeps the queue current.
+
+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.
+
+### Inbox Thread State
+
+The `assistant_inbox_thread_state` table provides a denormalized view of per-contact conversation threads, tracking unread counts, pending escalation counts, and last message timestamps. Threads are keyed by `conversationId` and bound to `(assistantId, sourceChannel, externalChatId)`. The escalation projection (`inbox-escalation-projection.ts`) keeps badge counts in sync with the `channel_guardian_approval_requests` table.
+
+### IPC Contracts
+
+| 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 |
+| `assistant_inbox` | list_threads, get_thread_messages | Query inbox threads and message history |
+| `assistant_inbox_escalation` | list, decide | List pending escalations and approve/deny from desktop |
+| `assistant_inbox_reply` | — | Send a reply to an external user from the desktop inbox |
+
+### Key Modules
+
+| File | Purpose |
+|------|---------|
+| `src/memory/ingress-invite-store.ts` | CRUD for invite tokens with SHA-256 hashing and expiry |
+| `src/memory/ingress-member-store.ts` | CRUD for ingress members with policy enforcement |
+| `src/memory/inbox-thread-store.ts` | Inbox thread state queries (unread counts, escalation badges) |
+| `src/memory/inbox-escalation-projection.ts` | Projects escalation state from approval requests onto thread state |
+| `src/daemon/handlers/config-inbox.ts` | IPC handlers for all inbox contracts |
+| `src/daemon/ipc-contract/inbox.ts` | TypeScript type definitions for inbox IPC messages |
+| `src/runtime/routes/channel-routes.ts` | ACL enforcement point — member lookup, policy check, escalation creation |
+
 ## 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).

package/eslint.config.mjs

@@ -10,6 +10,37 @@ const eslintConfig = defineConfig([
         "error",
         { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
       ],
+
+      // Standardize on `undefined` only — avoid `null` in new code.
+      // Prefer `=== undefined`, `?? fallback`, or `?.` optional chaining
+      // instead of `=== null`.
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "BinaryExpression[operator='==='][right.type='Literal'][right.raw='null']",
+          message:
+            "Avoid `=== null`. Prefer `=== undefined`, `?? fallback`, or optional chaining `?.` instead.",
+        },
+        {
+          selector:
+            "BinaryExpression[operator='==='][left.type='Literal'][left.raw='null']",
+          message:
+            "Avoid `null ===`. Prefer `=== undefined`, `?? fallback`, or optional chaining `?.` instead.",
+        },
+        {
+          selector:
+            "BinaryExpression[operator='!=='][right.type='Literal'][right.raw='null']",
+          message:
+            "Avoid `!== null`. Prefer `!== undefined`, nullish coalescing `??`, or optional chaining `?.` instead.",
+        },
+        {
+          selector:
+            "BinaryExpression[operator='!=='][left.type='Literal'][left.raw='null']",
+          message:
+            "Avoid `null !==`. Prefer `!== undefined`, nullish coalescing `??`, or optional chaining `?.` instead.",
+        },
+      ],
     },
   },
 ]);

package/package.json

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

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

@@ -53,6 +53,9 @@ const SWIFT_OMIT_ALLOWLIST = new Set<string>([
   'browser_handoff_request',
   // 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',
   // Work item messages — not yet consumed by the macOS client
   'work_item_get_response',
   'work_item_run_task_response',
@@ -99,7 +102,7 @@ function extractSwiftDecodeCases(swiftSource: string): Set<string> {
 
   const decoderSection = swiftSource.slice(decoderStart);
 
-  while ((match = re.exec(decoderSection)) !== null) {
+  while ((match = re.exec(decoderSection)) != null) {
     cases.add(match[1]);
   }
 

package/scripts/ipc/generate-swift.ts

@@ -21,11 +21,25 @@ import * as TJS from 'typescript-json-schema';
 
 const ROOT = path.resolve(import.meta.dirname ?? __dirname, '../..');
 const CONTRACT_PATH = path.join(ROOT, 'src/daemon/ipc-contract.ts');
+const DOMAIN_DIR = path.join(ROOT, 'src/daemon/ipc-contract');
 const OUTPUT_PATH = path.resolve(
   ROOT,
   '../clients/shared/IPC/Generated/IPCContractGenerated.swift',
 );
 
+/** Collect all .ts files: the barrel + domain files. */
+function getContractFiles(): string[] {
+  const files = [CONTRACT_PATH];
+  if (fs.existsSync(DOMAIN_DIR)) {
+    for (const f of fs.readdirSync(DOMAIN_DIR)) {
+      if (f.endsWith('.ts')) {
+        files.push(path.join(DOMAIN_DIR, f));
+      }
+    }
+  }
+  return files;
+}
+
 const PREAMBLE = `// AUTO-GENERATED from assistant/src/daemon/ipc-contract.ts — DO NOT EDIT
 // Regenerate: cd assistant && bun run generate:ipc
 //
@@ -76,7 +90,9 @@ interface SchemaDef {
 // --- Step 1: Generate JSON Schema from TypeScript ---
 
 function generateSchemas(): Record<string, SchemaDef> {
-  const program = TJS.getProgramFromFiles([CONTRACT_PATH], {
+  const contractFiles = getContractFiles();
+
+  const program = TJS.getProgramFromFiles(contractFiles, {
     strict: true,
     target: 99,
     module: 199,
@@ -95,7 +111,7 @@ function generateSchemas(): Record<string, SchemaDef> {
     throw new Error('Failed to create schema generator');
   }
 
-  const symbols = generator.getMainFileSymbols(program, [CONTRACT_PATH]);
+  const symbols = generator.getMainFileSymbols(program, contractFiles);
   const result: Record<string, SchemaDef> = {};
 
   const skipped: string[] = [];

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

@@ -37,7 +37,7 @@ exports[`IPC message snapshots ClientMessage types session_create serializes to
   "threadType": "standard",
   "title": "New session",
   "transport": {
-    "channelId": "desktop",
+    "channelId": "macos",
     "hints": [
       "dashboard-capable",
     ],
@@ -374,6 +374,13 @@ exports[`IPC message snapshots ClientMessage types schedule_remove serializes to
 }
 `;
 
+exports[`IPC message snapshots ClientMessage types schedule_run_now serializes to expected JSON 1`] = `
+{
+  "id": "sched-001",
+  "type": "schedule_run_now",
+}
+`;
+
 exports[`IPC message snapshots ClientMessage types reminders_list serializes to expected JSON 1`] = `
 {
   "type": "reminders_list",
@@ -475,6 +482,15 @@ exports[`IPC message snapshots ClientMessage types sessions_clear serializes to
 }
 `;
 
+exports[`IPC message snapshots ClientMessage types conversation_search serializes to expected JSON 1`] = `
+{
+  "limit": 20,
+  "maxMessagesPerConversation": 3,
+  "query": "hello world",
+  "type": "conversation_search",
+}
+`;
+
 exports[`IPC message snapshots ClientMessage types ipc_blob_probe serializes to expected JSON 1`] = `
 {
   "nonceSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
@@ -931,6 +947,95 @@ exports[`IPC message snapshots ClientMessage types dictation_request serializes
 }
 `;
 
+exports[`IPC message snapshots ClientMessage types parental_control_get serializes to expected JSON 1`] = `
+{
+  "type": "parental_control_get",
+}
+`;
+
+exports[`IPC message snapshots ClientMessage types parental_control_verify_pin serializes to expected JSON 1`] = `
+{
+  "pin": "123456",
+  "type": "parental_control_verify_pin",
+}
+`;
+
+exports[`IPC message snapshots ClientMessage types parental_control_set_pin serializes to expected JSON 1`] = `
+{
+  "current_pin": "123456",
+  "new_pin": "654321",
+  "type": "parental_control_set_pin",
+}
+`;
+
+exports[`IPC message snapshots ClientMessage types parental_control_update serializes to expected JSON 1`] = `
+{
+  "blocked_tool_categories": [
+    "shell",
+    "network",
+  ],
+  "content_restrictions": [
+    "violence",
+    "adult_content",
+  ],
+  "enabled": true,
+  "pin": "123456",
+  "type": "parental_control_update",
+}
+`;
+
+exports[`IPC message snapshots ClientMessage types ingress_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",
+}
+`;
+
+exports[`IPC message snapshots ClientMessage types assistant_inbox serializes to expected JSON 1`] = `
+{
+  "action": "list_threads",
+  "assistantId": "asst-001",
+  "limit": 20,
+  "offset": 0,
+  "type": "assistant_inbox",
+}
+`;
+
+exports[`IPC message snapshots ClientMessage types assistant_inbox_escalation serializes to expected JSON 1`] = `
+{
+  "action": "list",
+  "assistantId": "asst-001",
+  "status": "pending",
+  "type": "assistant_inbox_escalation",
+}
+`;
+
+exports[`IPC message snapshots ClientMessage types assistant_inbox_reply serializes to expected JSON 1`] = `
+{
+  "content": "Hello from the assistant",
+  "conversationId": "conv-001",
+  "type": "assistant_inbox_reply",
+}
+`;
+
 exports[`IPC message snapshots ServerMessage types auth_result serializes to expected JSON 1`] = `
 {
   "success": true,
@@ -1086,6 +1191,14 @@ exports[`IPC message snapshots ServerMessage types session_info serializes to ex
 }
 `;
 
+exports[`IPC message snapshots ServerMessage types session_title_updated serializes to expected JSON 1`] = `
+{
+  "sessionId": "sess-001",
+  "title": "Plan sprint rollout",
+  "type": "session_title_updated",
+}
+`;
+
 exports[`IPC message snapshots ServerMessage types session_list_response serializes to expected JSON 1`] = `
 {
   "sessions": [
@@ -1113,6 +1226,28 @@ exports[`IPC message snapshots ServerMessage types sessions_clear_response seria
 }
 `;
 
+exports[`IPC message snapshots ServerMessage types conversation_search_response serializes to expected JSON 1`] = `
+{
+  "query": "hello world",
+  "results": [
+    {
+      "conversationId": "conv-001",
+      "conversationTitle": "My Conversation",
+      "conversationUpdatedAt": 1700000000,
+      "matchingMessages": [
+        {
+          "createdAt": 1699999000,
+          "excerpt": "…hello world, how are you?…",
+          "messageId": "msg-001",
+          "role": "user",
+        },
+      ],
+    },
+  ],
+  "type": "conversation_search_response",
+}
+`;
+
 exports[`IPC message snapshots ServerMessage types error serializes to expected JSON 1`] = `
 {
   "message": "Something went wrong",
@@ -2475,6 +2610,17 @@ exports[`IPC message snapshots ServerMessage types task_run_thread_created seria
 }
 `;
 
+exports[`IPC message snapshots ServerMessage types guardian_request_thread_created serializes to expected JSON 1`] = `
+{
+  "callSessionId": "call-001",
+  "conversationId": "conv-guardian-001",
+  "questionText": "What is the gate code?",
+  "requestId": "req-guardian-001",
+  "title": "Guardian action request",
+  "type": "guardian_request_thread_created",
+}
+`;
+
 exports[`IPC message snapshots ServerMessage types subagent_spawned serializes to expected JSON 1`] = `
 {
   "label": "Research Agent",
@@ -2599,3 +2745,194 @@ exports[`IPC message snapshots ServerMessage types dictation_response serializes
   "type": "dictation_response",
 }
 `;
+
+exports[`IPC message snapshots ServerMessage types parental_control_get_response serializes to expected JSON 1`] = `
+{
+  "blocked_tool_categories": [
+    "shell",
+    "network",
+  ],
+  "content_restrictions": [
+    "violence",
+    "adult_content",
+  ],
+  "enabled": true,
+  "has_pin": true,
+  "type": "parental_control_get_response",
+}
+`;
+
+exports[`IPC message snapshots ServerMessage types parental_control_verify_pin_response serializes to expected JSON 1`] = `
+{
+  "type": "parental_control_verify_pin_response",
+  "verified": true,
+}
+`;
+
+exports[`IPC message snapshots ServerMessage types parental_control_set_pin_response serializes to expected JSON 1`] = `
+{
+  "success": true,
+  "type": "parental_control_set_pin_response",
+}
+`;
+
+exports[`IPC message snapshots ServerMessage types parental_control_update_response serializes to expected JSON 1`] = `
+{
+  "blocked_tool_categories": [
+    "shell",
+    "network",
+  ],
+  "content_restrictions": [
+    "violence",
+    "adult_content",
+  ],
+  "enabled": true,
+  "has_pin": true,
+  "success": true,
+  "type": "parental_control_update_response",
+}
+`;
+
+exports[`IPC message snapshots ServerMessage types ingress_invite_response serializes to expected JSON 1`] = `
+{
+  "invite": {
+    "createdAt": 1700000000,
+    "expiresAt": 1700100000000,
+    "id": "inv-001",
+    "maxUses": 5,
+    "note": "Test invite",
+    "sourceChannel": "telegram",
+    "status": "active",
+    "token": "tok-abc123",
+    "tokenHash": "hash-abc123",
+    "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",
+}
+`;
+
+exports[`IPC message snapshots ServerMessage types assistant_inbox_response serializes to expected JSON 1`] = `
+{
+  "success": true,
+  "threads": [
+    {
+      "conversationId": "conv-001",
+      "displayName": "Test User",
+      "externalChatId": "chat-456",
+      "externalUserId": "user-123",
+      "hasPendingEscalation": false,
+      "lastInboundAt": 1700000000,
+      "lastMessageAt": 1700000000,
+      "lastOutboundAt": 1699999000,
+      "sourceChannel": "telegram",
+      "unreadCount": 3,
+      "username": "testuser",
+    },
+  ],
+  "type": "assistant_inbox_response",
+}
+`;
+
+exports[`IPC message snapshots ServerMessage types assistant_inbox_escalation_response serializes to expected JSON 1`] = `
+{
+  "escalations": [
+    {
+      "channel": "telegram",
+      "conversationId": "conv-001",
+      "createdAt": 1700000000,
+      "id": "esc-001",
+      "requestSummary": "User wants to delete their account",
+      "requesterChatId": "chat-456",
+      "requesterExternalUserId": "user-123",
+      "runId": "run-001",
+      "status": "pending",
+    },
+  ],
+  "success": true,
+  "type": "assistant_inbox_escalation_response",
+}
+`;
+
+exports[`IPC message snapshots ServerMessage types assistant_inbox_reply_response serializes to expected JSON 1`] = `
+{
+  "messageId": "msg-reply-001",
+  "success": true,
+  "type": "assistant_inbox_reply_response",
+}
+`;
+
+exports[`IPC message snapshots ClientMessage types pairing_approval_response serializes to expected JSON 1`] = `
+{
+  "decision": "approve_once",
+  "pairingRequestId": "pair-001",
+  "type": "pairing_approval_response",
+}
+`;
+
+exports[`IPC message snapshots ClientMessage types approved_devices_list serializes to expected JSON 1`] = `
+{
+  "type": "approved_devices_list",
+}
+`;
+
+exports[`IPC message snapshots ClientMessage types approved_device_remove serializes to expected JSON 1`] = `
+{
+  "hashedDeviceId": "hashed-device-001",
+  "type": "approved_device_remove",
+}
+`;
+
+exports[`IPC message snapshots ClientMessage types approved_devices_clear serializes to expected JSON 1`] = `
+{
+  "type": "approved_devices_clear",
+}
+`;
+
+exports[`IPC message snapshots ServerMessage types pairing_approval_request serializes to expected JSON 1`] = `
+{
+  "deviceId": "device-001",
+  "deviceName": "iPhone 15",
+  "pairingRequestId": "pair-001",
+  "type": "pairing_approval_request",
+}
+`;
+
+exports[`IPC message snapshots ServerMessage types approved_devices_list_response serializes to expected JSON 1`] = `
+{
+  "devices": [
+    {
+      "deviceName": "iPhone 15",
+      "hashedDeviceId": "hashed-device-001",
+      "lastPairedAt": 1700000000000,
+    },
+  ],
+  "type": "approved_devices_list_response",
+}
+`;
+
+exports[`IPC message snapshots ServerMessage types approved_device_remove_response serializes to expected JSON 1`] = `
+{
+  "success": true,
+  "type": "approved_device_remove_response",
+}
+`;