@vellumai/assistant 0.3.12 → 0.3.14

package/ARCHITECTURE.md

@@ -57,6 +57,14 @@ The HTTP route handlers (`integration-routes.ts`) and the legacy IPC handlers (`
 | `src/daemon/handlers/config-channels.ts` | IPC handler that delegates to the same shared actions |
 | `src/config/vellum-skills/guardian-verify-setup/SKILL.md` | Skill that teaches the assistant how to orchestrate guardian verification via chat |
 
+**Guardian-Only Tool Invocation Gate:**
+
+Guardian verification control-plane endpoints (`/v1/integrations/guardian/*`) are protected by a deterministic gate in the tool executor (`src/tools/executor.ts`). Before any tool invocation proceeds, the executor checks whether the invocation targets a guardian control-plane endpoint and whether the actor role is allowed. The policy uses an allowlist: only `guardian` and `undefined` (desktop/trusted) actor roles can invoke these endpoints. Non-guardian and unverified-channel actors receive a denial message explaining the restriction.
+
+The policy is implemented in `src/tools/guardian-control-plane-policy.ts`, which inspects tool inputs (bash commands, URLs) for guardian endpoint paths. This is a defense-in-depth measure — even if the LLM attempts to call guardian endpoints on behalf of a non-guardian actor, the tool executor blocks it deterministically.
+
+The `guardian-verify-setup` skill is the exclusive handler for guardian verification intents in the system prompt. Other skills (e.g., `phone-calls`) hand off to `guardian-verify-setup` rather than orchestrating verification directly.
+
 ### SMS Channel (Twilio)
 
 The SMS channel provides text-only messaging via Twilio, sharing the same telephony provider as voice calls. It follows the same ingress/egress pattern as Telegram but uses Twilio's HMAC-SHA1 signature validation instead of a secret header.
@@ -170,7 +178,7 @@ graph LR
         EMB["memory_embeddings<br/>───────────────<br/>target: segment | item | summary<br/>provider + model metadata<br/>vector_json (float array)<br/>Powers semantic search"]
         JOBS["memory_jobs<br/>───────────────<br/>Async task queue<br/>Types: embed, extract,<br/>summarize, backfill,<br/>conflict resolution, cleanup<br/>Status: pending → running →<br/>completed | failed"]
         ATT["attachments<br/>───────────────<br/>base64-encoded file data<br/>mime_type, size_bytes<br/>Linked to messages via<br/>message_attachments join"]
-        REM["reminders<br/>───────────────<br/>One-time scheduled reminders<br/>label, message, fireAt<br/>mode: notify | execute<br/>status: pending → fired | cancelled"]
+        REM["reminders<br/>───────────────<br/>One-time scheduled reminders<br/>label, message, fireAt<br/>mode: notify | execute<br/>status: pending → fired | cancelled<br/>routing_intent: single_channel |<br/>multi_channel | all_channels<br/>routing_hints_json (free-form)"]
         SCHED_JOBS["cron_jobs (recurrence schedules)<br/>───────────────<br/>Recurring schedule definitions<br/>cron_expression: cron or RRULE string<br/>schedule_syntax: 'cron' | 'rrule'<br/>timezone, message, next_run_at<br/>enabled, retry_count<br/>Legacy alias: scheduleJobs"]
         SCHED_RUNS["cron_runs (schedule runs)<br/>───────────────<br/>Execution history per schedule<br/>job_id (FK → cron_jobs)<br/>status: ok | error<br/>duration_ms, output, error<br/>Legacy alias: scheduleRuns"]
         TASKS["tasks<br/>───────────────<br/>Reusable prompt templates<br/>title, Handlebars template<br/>inputSchema, contextFlags<br/>requiredTools, status"]
@@ -1440,14 +1448,19 @@ Two IPC push events surface new threads in the macOS/iOS client sidebar:
 
 All events follow the same pattern: the daemon creates a server-side conversation, persists an initial message, and broadcasts the IPC event so the macOS `ThreadManager` can create a visible thread in the sidebar.
 
+### Reminder Routing Metadata
+
+Reminders carry optional `routingIntent` (`single_channel` | `multi_channel` | `all_channels`) and free-form `routingHints` metadata. When a reminder fires, this metadata flows through the notification signal into a post-decision enforcement step (`enforceRoutingIntent()` in `decision-engine.ts`) that overrides the LLM's channel selection to match the requested coverage. This enables single-reminder fanout: one reminder can produce multi-channel delivery without duplicate reminders. See `assistant/docs/architecture/scheduling.md` for the full trigger-time data flow.
+
 ### Channel Delivery
 
-Notifications are delivered to two channel types:
+Notifications are delivered to three channel types:
 
 - **Vellum (always connected)**: Local IPC via the daemon's broadcast mechanism. The `VellumAdapter` emits a `notification_intent` message with rendered copy and optional `deepLinkMetadata`.
 - **Telegram (when guardian binding exists)**: HTTP POST to the gateway's `/deliver/telegram` endpoint. Requires an active guardian binding for the assistant.
+- **SMS (when guardian binding exists)**: HTTP POST to the gateway's `/deliver/sms` endpoint. Follows the same pattern as Telegram; the `SmsAdapter` sends text-only messages via the Twilio Messages API. The `assistantId` is threaded through the delivery payload for multi-assistant phone number resolution.
 
-Connected channels are resolved at signal emission time: vellum is always included, and binding-based channels (Telegram) are included only when an active guardian binding exists for the assistant.
+Connected channels are resolved at signal emission time: vellum is always included, and binding-based channels (Telegram, SMS) are included only when an active guardian binding exists for the assistant.
 
 **Key modules:**
 
@@ -1461,6 +1474,7 @@ Connected channels are resolved at signal emission time: vellum is always includ
 | `assistant/src/notifications/conversation-pairing.ts` | Materializes conversation + message per delivery based on channel strategy |
 | `assistant/src/notifications/adapters/macos.ts` | Vellum adapter — broadcasts `notification_intent` via IPC with deep-link metadata |
 | `assistant/src/notifications/adapters/telegram.ts` | Telegram adapter — POSTs to gateway `/deliver/telegram` |
+| `assistant/src/notifications/adapters/sms.ts` | SMS adapter — POSTs to gateway `/deliver/sms` via Twilio Messages API |
 | `assistant/src/notifications/destination-resolver.ts` | Resolves per-channel endpoints (vellum IPC, Telegram chat ID from guardian binding) |
 | `assistant/src/notifications/copy-composer.ts` | Template-based fallback copy when LLM copy is unavailable |
 | `assistant/src/notifications/preference-extractor.ts` | Detects preference statements in conversation messages |

package/README.md

@@ -343,6 +343,8 @@ Guardian verification can also be initiated through normal desktop chat. When th
 
 These endpoints share the same business logic as the IPC-based verification flow via `guardian-outbound-actions.ts`.
 
+**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
 
 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.

package/docs/architecture/scheduling.md

@@ -43,6 +43,87 @@ The database column is named `cron_expression` and the Drizzle table is `cronJob
 
 ---
 
+## Reminder Routing — Trigger-Time Multi-Channel Delivery
+
+Reminders support optional routing metadata that controls how the notification pipeline fans out delivery across channels when a reminder fires. This allows a single reminder to reach the user on multiple channels (desktop, Telegram, SMS) without requiring duplicate reminders.
+
+### Routing Metadata Model
+
+Two columns on the `reminders` table carry routing metadata:
+
+| Column | Type | Default | Description |
+|--------|------|---------|-------------|
+| `routing_intent` | TEXT | `'single_channel'` | Controls channel coverage: `single_channel`, `multi_channel`, or `all_channels` |
+| `routing_hints_json` | TEXT (JSON) | `'{}'` | Free-form hints for the decision engine (e.g. preferred channels) |
+
+### Trigger-Time Data Flow
+
+When the scheduler fires a reminder, routing metadata flows through the full notification pipeline:
+
+```mermaid
+sequenceDiagram
+    participant Scheduler as Scheduler<br/>(15s tick)
+    participant Store as ReminderStore<br/>(SQLite)
+    participant Lifecycle as Daemon Lifecycle<br/>(notifyReminder)
+    participant Signal as emitNotificationSignal
+    participant Engine as Decision Engine<br/>(LLM)
+    participant Enforce as enforceRoutingIntent
+    participant Broadcaster as Broadcaster
+    participant Adapters as Channel Adapters<br/>(Vellum, Telegram, SMS)
+
+    Scheduler->>Store: claimDueReminders(now)
+    Store-->>Scheduler: ReminderRow[] (with routingIntent, routingHints)
+    Scheduler->>Lifecycle: notifyReminder({ id, label, message, routingIntent, routingHints })
+    Lifecycle->>Signal: emitNotificationSignal({ routingIntent, routingHints, ... })
+    Signal->>Engine: evaluateSignal(signal, connectedChannels)
+    Engine-->>Signal: NotificationDecision (LLM channel selection)
+    Signal->>Enforce: enforceRoutingIntent(decision, routingIntent, connectedChannels)
+    Note over Enforce: Override channel selection<br/>based on routing intent
+    Enforce-->>Signal: Enforced decision (re-persisted if changed)
+    Signal->>Broadcaster: dispatchDecision(signal, decision)
+    Broadcaster->>Adapters: Fan-out to each selected channel
+```
+
+### Enforcement Behavior
+
+The `enforceRoutingIntent()` step runs after the LLM produces a channel selection but before deterministic checks. It acts as a post-decision guard:
+
+| Intent | Enforcement Rule |
+|--------|-----------------|
+| `single_channel` | No override. The LLM's channel selection stands. |
+| `multi_channel` | If the LLM selected < 2 channels and 2+ are connected, expand to all connected channels. |
+| `all_channels` | Replace the LLM's selection with all connected channels. |
+
+When enforcement changes the decision, the updated `selectedChannels` and annotated `reasoningSummary` are re-persisted to `notification_decisions` so the audit trail reflects what was actually dispatched.
+
+### Single-Reminder Fanout
+
+One reminder creates one notification signal. The routing intent on that single signal controls how many channels receive the notification. The notification pipeline handles per-channel copy rendering, conversation pairing, and delivery through existing adapters. No duplicate reminders are needed for multi-channel delivery.
+
+### Connected Channels at Fire Time
+
+Channel availability is resolved when the signal is emitted (not when the reminder is created):
+
+- **Vellum** — always connected (local IPC)
+- **Telegram** — connected when an active guardian binding exists
+- **SMS** — connected when an active guardian binding exists
+
+If a channel becomes unavailable between reminder creation and fire time, it is silently excluded from delivery. The routing intent enforcement operates only on channels that are connected at fire time.
+
+### Key Source Files
+
+| File | Responsibility |
+|------|---------------|
+| `assistant/src/tools/reminder/reminder-store.ts` | CRUD with `routingIntent` and `routingHints` fields |
+| `assistant/src/memory/schema.ts` | `reminders` table schema with `routing_intent` and `routing_hints_json` columns |
+| `assistant/src/schedule/scheduler.ts` | Claims due reminders and passes routing metadata to the notifier |
+| `assistant/src/daemon/lifecycle.ts` | Wires the reminder notifier to `emitNotificationSignal()` with routing metadata |
+| `assistant/src/notifications/emit-signal.ts` | Orchestrates the full pipeline including routing intent enforcement |
+| `assistant/src/notifications/decision-engine.ts` | `enforceRoutingIntent()` post-decision guard |
+| `assistant/src/notifications/signal.ts` | `RoutingIntent` type and `NotificationSignal` fields |
+
+---
+
 ## Watcher System — Event-Driven Polling
 
 Watchers poll external APIs on an interval, detect new events via watermark-based change tracking, and process them through a background LLM session.

package/package.json

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

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

@@ -9,6 +9,10 @@ exports[`IPC message snapshots ClientMessage types auth serializes to expected J
 
 exports[`IPC message snapshots ClientMessage types user_message serializes to expected JSON 1`] = `
 {
+  "commandIntent": {
+    "action": "start",
+    "domain": "screen_recording",
+  },
   "content": "Hello, assistant!",
   "interface": "cli",
   "sessionId": "sess-001",
@@ -206,6 +210,10 @@ exports[`IPC message snapshots ClientMessage types watch_observation serializes
 
 exports[`IPC message snapshots ClientMessage types task_submit serializes to expected JSON 1`] = `
 {
+  "commandIntent": {
+    "action": "start",
+    "domain": "screen_recording",
+  },
   "screenHeight": 1080,
   "screenWidth": 1920,
   "task": "Open Safari and search for weather",
@@ -3056,6 +3064,20 @@ exports[`IPC message snapshots ServerMessage types approved_device_remove_respon
 }
 `;
 
+exports[`IPC message snapshots ServerMessage types recording_pause serializes to expected JSON 1`] = `
+{
+  "recordingId": "rec-001",
+  "type": "recording_pause",
+}
+`;
+
+exports[`IPC message snapshots ServerMessage types recording_resume serializes to expected JSON 1`] = `
+{
+  "recordingId": "rec-001",
+  "type": "recording_resume",
+}
+`;
+
 exports[`IPC message snapshots ServerMessage types recording_start serializes to expected JSON 1`] = `
 {
   "recordingId": "rec-001",

package/src/__tests__/channel-policy.test.ts

@@ -97,6 +97,7 @@ describe('channel policy registry', () => {
     const expectedStrategies: [ChannelId, ConversationStrategy][] = [
       ['vellum', 'start_new_conversation'],
       ['telegram', 'continue_existing_conversation'],
+      ['sms', 'continue_existing_conversation'],
       ['voice', 'not_deliverable'],
     ];
 
@@ -118,6 +119,24 @@ describe('channel policy registry', () => {
     }
   });
 
+  // ── SMS channel policy ───────────────────────────────────────────────
+
+  test('SMS is a deliverable notification channel', () => {
+    expect(isNotificationDeliverable('sms')).toBe(true);
+    expect(getDeliverableChannels()).toContain('sms');
+  });
+
+  test('SMS uses continue_existing_conversation strategy', () => {
+    expect(getConversationStrategy('sms')).toBe('continue_existing_conversation');
+  });
+
+  test('all_channels includes SMS when SMS is deliverable', () => {
+    const deliverable = getDeliverableChannels();
+    expect(deliverable).toContain('vellum');
+    expect(deliverable).toContain('telegram');
+    expect(deliverable).toContain('sms');
+  });
+
   // ── Consistency checks ────────────────────────────────────────────────
 
   test('channels with not_deliverable strategy have deliveryEnabled: false', () => {