@vellumai/assistant 0.3.4 → 0.3.6

package/Dockerfile

@@ -42,11 +42,13 @@ RUN apt-get update && apt-get install -y \
     fonts-freefont-ttf \
     make \
     g++ \
+    git \
     sudo \
     && rm -rf /var/lib/apt/lists/*
 
 # Copy bun binary from builder instead of re-installing
 COPY --from=builder /root/.bun/bin/bun /usr/local/bin/bun
+RUN ln -sf /usr/local/bin/bun /usr/local/bin/bunx
 
 # Create non-root user that also has sudo access so it can like install stuff
 RUN groupadd --system --gid 1001 assistant && \

package/README.md

@@ -194,7 +194,7 @@ The `/channels/inbound` endpoint requires a valid `X-Gateway-Origin` header to p
 
 ## Twilio Setup Primitive
 
-Twilio is the shared telephony provider for both voice calls and SMS messaging. Configuration is managed through the `twilio_config` IPC contract and the `twilio-setup` skill.
+Twilio is the shared telephony provider for both voice calls and SMS messaging. Configuration is managed through the `twilio_config` IPC contract and the `twilio-setup` skill. 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_config` IPC Contract
 
@@ -208,8 +208,15 @@ The daemon handles `twilio_config` messages with the following actions:
 | `provision_number` | Purchases a new phone number via the Twilio API. Accepts optional `areaCode` and `country` (ISO 3166-1 alpha-2, default `US`). Auto-assigns the number to the assistant (persists to config and secure storage) and configures Twilio webhooks (voice, status callback, SMS) when a public ingress URL is available. |
 | `assign_number` | Assigns an existing Twilio phone number (E.164 format) to the assistant and auto-configures webhooks when ingress is available |
 | `list_numbers` | Lists all incoming phone numbers on the Twilio account with their capabilities (voice, SMS) |
+| `sms_compliance_status` | Returns the SMS compliance posture for the assigned phone number. Determines number type (toll-free vs local 10DLC) and retrieves toll-free verification status from Twilio. |
+| `sms_submit_tollfree_verification` | Submits a new toll-free verification request to Twilio. Validates required fields and enum values. Defaults `businessType` to `SOLE_PROPRIETOR`. |
+| `sms_update_tollfree_verification` | Updates an existing toll-free verification by SID. Requires `verificationSid`. |
+| `sms_delete_tollfree_verification` | Deletes a toll-free verification by SID. Includes warning about queue priority reset. |
+| `release_number` | Releases (deletes) a phone number from the Twilio account. Clears the number from config and secure storage. Includes warning about toll-free verification context loss. |
+| `sms_send_test` | Sends a test SMS to the specified `phoneNumber` with the given `text`, polls Twilio for delivery status (up to 3 retries at 2-second intervals), and returns the result in `testResult`. Stores the last result in memory for use by `sms_doctor`. |
+| `sms_doctor` | Runs a comprehensive SMS health diagnostic. Checks channel readiness, compliance/toll-free verification status, and the last `sms_send_test` result. Returns structured diagnostics in `diagnostics` with an overall `status` ("healthy", "degraded", or "unhealthy") and actionable `items`. |
 
-Response type: `twilio_config_response` with `success`, `hasCredentials`, optional `phoneNumber`, optional `numbers` array, optional `error`, and optional `warning` (for non-fatal webhook sync failures).
+Response type: `twilio_config_response` with `success`, `hasCredentials`, optional `phoneNumber`, optional `numbers` array, optional `error`, optional `warning` (for non-fatal webhook sync failures), optional `compliance` object (for compliance status actions, containing `numberType`, `verificationSid`, `verificationStatus`, `rejectionReason`, `rejectionReasons`, `errorCode`, `editAllowed`, `editExpiration`), optional `testResult` (for `sms_send_test`), and optional `diagnostics` (for `sms_doctor`).
 
 ### Ingress Webhook Reconciliation
 
@@ -251,6 +258,85 @@ Guardian bindings, verification challenges, and approval requests are all scoped
 
 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.
 
+## Channel Readiness
+
+The `channel_readiness` IPC contract provides a unified way to check whether a channel (SMS, Telegram, etc.) is fully configured and operational. It runs local checks (credential presence, phone number assignment, ingress config) synchronously and optional remote checks (API reachability) asynchronously with a 5-minute TTL cache.
+
+### `channel_readiness` IPC Contract
+
+| Action | Description |
+|--------|-------------|
+| `get` | Returns readiness snapshots for the specified channel (or all channels if omitted). Local checks always run; remote checks run only when `includeRemote=true` and cache is stale. |
+| `refresh` | Invalidates the cache for the specified channel (or all channels), then returns fresh snapshots. |
+
+Request fields: `action` (required), `channel` (optional filter), `assistantId` (optional), `includeRemote` (optional boolean).
+
+Response type: `channel_readiness_response` with `success`, optional `snapshots` array (each with `channel`, `ready`, `checkedAt`, `stale`, `reasons`, `localChecks`, optional `remoteChecks`), and optional `error`.
+
+### Built-in Channel Probes
+
+- **SMS**: Checks Twilio credentials, phone number assignment, and public ingress URL.
+- **Telegram**: Checks bot token, webhook secret, and public ingress URL.
+
+### Key modules
+
+| File | Purpose |
+|------|---------|
+| `src/runtime/channel-readiness-types.ts` | Shared types: `ChannelId`, `ReadinessCheckResult`, `ChannelReadinessSnapshot`, `ChannelProbe` |
+| `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.4",
+  "version": "0.3.6",
   "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[] = [];
@@ -405,6 +421,19 @@ function emitStruct(s: SwiftStruct): string {
     lines.push(`    public let ${p.swiftName}: ${p.swiftType}`);
   }
 
+  // Emit public memberwise init (Swift only auto-generates internal inits for public structs)
+  if (s.properties.length > 0) {
+    lines.push('');
+    const params = s.properties
+      .map((p) => `${p.swiftName}: ${p.swiftType}${p.isOptional ? ' = nil' : ''}`)
+      .join(', ');
+    lines.push(`    public init(${params}) {`);
+    for (const p of s.properties) {
+      lines.push(`        self.${p.swiftName} = ${p.swiftName}`);
+    }
+    lines.push('    }');
+  }
+
   if (needsCodingKeys(s.properties)) {
     lines.push('');
     lines.push('    private enum CodingKeys: String, CodingKey {');