@vellumai/assistant 0.3.7 → 0.3.9

package/src/daemon/session-runtime-assembly.ts

@@ -261,6 +261,26 @@ export function injectActiveSurfaceContext(message: Message, ctx: ActiveSurfaceC
   };
 }
 
+/**
+ * Append voice call-control protocol instructions to the last user
+ * message so the model knows how to emit control markers during voice
+ * turns routed through the session pipeline.
+ */
+export function injectVoiceCallControlContext(message: Message, prompt: string): Message {
+  return {
+    ...message,
+    content: [
+      ...message.content,
+      { type: 'text', text: prompt },
+    ],
+  };
+}
+
+/** Strip `<voice_call_control>` blocks injected by `injectVoiceCallControlContext`. */
+export function stripVoiceCallControlContext(messages: Message[]): Message[] {
+  return stripUserTextBlocksByPrefix(messages, ['<voice_call_control>']);
+}
+
 /**
  * Prepend channel capability context to the last user message so the
  * model knows what the current channel can and cannot do.
@@ -514,6 +534,7 @@ const RUNTIME_INJECTION_PREFIXES = [
   '<channel_command_context>',
   '<channel_turn_context>',
   '<guardian_context>',
+  '<voice_call_control>',
   '<workspace_top_level>',
   TEMPORAL_INJECTED_PREFIX,
   '<active_workspace>',
@@ -558,10 +579,21 @@ export function applyRuntimeInjections(
     channelTurnContext?: ChannelTurnContextParams | null;
     guardianContext?: GuardianRuntimeContext | null;
     temporalContext?: string | null;
+    voiceCallControlPrompt?: string | null;
   },
 ): Message[] {
   let result = runMessages;
 
+  if (options.voiceCallControlPrompt) {
+    const userTail = result[result.length - 1];
+    if (userTail && userTail.role === 'user') {
+      result = [
+        ...result.slice(0, -1),
+        injectVoiceCallControlContext(userTail, options.voiceCallControlPrompt),
+      ];
+    }
+  }
+
   if (options.softConflictInstruction) {
     const userTail = result[result.length - 1];
     if (userTail && userTail.role === 'user') {

package/src/daemon/session.ts

@@ -130,6 +130,7 @@ export class Session {
   /** @internal */ currentPage?: string;
   /** @internal */ channelCapabilities?: ChannelCapabilities;
   /** @internal */ guardianContext?: GuardianRuntimeContext;
+  /** @internal */ voiceCallControlPrompt?: string;
   /** @internal */ assistantId?: string;
   /** @internal */ commandIntent?: { type: string; payload?: string; languageCode?: string };
   /** @internal */ pendingSurfaceActions = new Map<string, { surfaceType: SurfaceType }>();
@@ -344,6 +345,10 @@ export class Session {
     this.guardianContext = ctx ?? undefined;
   }
 
+  setVoiceCallControlPrompt(prompt: string | null): void {
+    this.voiceCallControlPrompt = prompt ?? undefined;
+  }
+
   setAssistantId(assistantId: string | null): void {
     this.assistantId = assistantId ?? undefined;
   }

package/src/memory/db-init.ts

@@ -16,6 +16,7 @@ import {
   migrateGuardianActionTables,
   migrateBackfillInboxThreadStateFromBindings,
   migrateDropActiveSearchIndex,
+  migrateNotificationTablesSchema,
   migrateMemorySegmentsIndexes,
   migrateMemoryItemsIndexes,
   migrateRemainingTableIndexes,
@@ -1276,5 +1277,84 @@ export function initializeDb(): void {
 
   migrateRemainingTableIndexes(database);
 
+  // ── Notification System ──────────────────────────────────────────────
+
+  // Migration: drop legacy enum-based notification tables if old schema detected.
+  // Guarded behind a one-time check for the old `notification_type` column.
+  migrateNotificationTablesSchema(database);
+
+  database.run(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS notification_preferences (
+      id TEXT PRIMARY KEY,
+      assistant_id TEXT NOT NULL,
+      preference_text TEXT NOT NULL,
+      applies_when_json TEXT NOT NULL DEFAULT '{}',
+      priority INTEGER NOT NULL DEFAULT 0,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+
+  database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_preferences_assistant_id ON notification_preferences(assistant_id)`);
+  database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_preferences_assistant_priority ON notification_preferences(assistant_id, priority DESC)`);
+
+  database.run(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS notification_events (
+      id TEXT PRIMARY KEY,
+      assistant_id TEXT NOT NULL,
+      source_event_name TEXT NOT NULL,
+      source_channel TEXT NOT NULL,
+      source_session_id TEXT NOT NULL,
+      attention_hints_json TEXT NOT NULL DEFAULT '{}',
+      payload_json TEXT NOT NULL DEFAULT '{}',
+      dedupe_key TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+
+  database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_events_assistant_event_created ON notification_events(assistant_id, source_event_name, created_at)`);
+  database.run(/*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_notification_events_dedupe ON notification_events(assistant_id, dedupe_key) WHERE dedupe_key IS NOT NULL`);
+
+  database.run(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS notification_decisions (
+      id TEXT PRIMARY KEY,
+      notification_event_id TEXT NOT NULL REFERENCES notification_events(id) ON DELETE CASCADE,
+      should_notify INTEGER NOT NULL,
+      selected_channels TEXT NOT NULL DEFAULT '[]',
+      reasoning_summary TEXT NOT NULL,
+      confidence REAL NOT NULL,
+      fallback_used INTEGER NOT NULL DEFAULT 0,
+      prompt_version TEXT,
+      validation_results TEXT,
+      created_at INTEGER NOT NULL
+    )
+  `);
+
+  database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_decisions_event_id ON notification_decisions(notification_event_id)`);
+
+  database.run(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS notification_deliveries (
+      id TEXT PRIMARY KEY,
+      notification_decision_id TEXT NOT NULL REFERENCES notification_decisions(id) ON DELETE CASCADE,
+      assistant_id TEXT NOT NULL,
+      channel TEXT NOT NULL,
+      destination TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'pending',
+      attempt INTEGER NOT NULL DEFAULT 1,
+      rendered_title TEXT,
+      rendered_body TEXT,
+      error_code TEXT,
+      error_message TEXT,
+      sent_at INTEGER,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+
+  database.run(/*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_notification_deliveries_unique ON notification_deliveries(notification_decision_id, channel, destination, attempt)`);
+  database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_deliveries_decision_id ON notification_deliveries(notification_decision_id)`);
+  database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_deliveries_assistant_status ON notification_deliveries(assistant_id, status)`)
+
   validateMigrationState(database);
 }

package/src/memory/guardian-action-store.ts

@@ -7,7 +7,7 @@
  * answer resolves the request and all other deliveries are marked answered.
  */
 
-import { and, eq, lt, inArray } from 'drizzle-orm';
+import { and, eq, inArray, lt } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 import { getDb, rawChanges } from './db.js';
 import {
@@ -337,7 +337,7 @@ export function createGuardianActionDelivery(params: {
 }
 
 /**
- * Look up pending deliveries for a specific destination.
+ * Look up sent deliveries for a specific destination.
  * Used by inbound message routing to match incoming answers to deliveries.
  */
 export function getPendingDeliveriesByDestination(

package/src/memory/migrations/016-memory-segments-indexes.ts

@@ -8,4 +8,5 @@ import type { DrizzleDb } from '../db-connection.js';
  */
 export function migrateMemorySegmentsIndexes(database: DrizzleDb): void {
   database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_memory_segments_scope_id ON memory_segments(scope_id)`);
+  database.run(/*sql*/ `DROP INDEX IF EXISTS idx_memory_segments_conversation_id`);
 }

package/src/memory/migrations/019-notification-tables-schema-migration.ts

@@ -0,0 +1,70 @@
+import { getSqliteFrom, type DrizzleDb } from '../db-connection.js';
+
+/**
+ * One-time migration: drop legacy enum-based notification tables so they can
+ * be recreated with the new signal-contract schema.
+ *
+ * Guard: only runs when the old `notification_type` column exists on the
+ * `notification_events` table (the old enum-based schema).  On fresh installs
+ * the table either doesn't exist yet or was created with the new schema, so
+ * CREATE TABLE IF NOT EXISTS in db-init handles idempotent creation.
+ *
+ * Drop order matters because of FK references:
+ *   notification_deliveries -> notification_events  (old schema FK)
+ *   notification_decisions  -> notification_events  (new schema FK, may exist from partial upgrade)
+ *   notification_events     (the table being rebuilt)
+ *   notification_preferences (fully removed, replaced by decision engine)
+ */
+export function migrateNotificationTablesSchema(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+  const checkpointKey = 'migration_notification_tables_schema_v1';
+  const checkpoint = raw.query(
+    `SELECT 1 FROM memory_checkpoints WHERE key = ?`,
+  ).get(checkpointKey);
+  if (checkpoint) return;
+
+  // Check if the old schema is present: the legacy notification_events table
+  // had a `notification_type` column that the new schema does not.
+  const hasOldSchema = raw.query(
+    `SELECT COUNT(*) as cnt FROM pragma_table_info('notification_events') WHERE name = 'notification_type'`,
+  ).get() as { cnt: number } | undefined;
+
+  if (hasOldSchema && hasOldSchema.cnt > 0) {
+    try {
+      raw.exec('BEGIN');
+
+      // Drop in FK-safe order: children before parents
+      raw.exec(/*sql*/ `DROP TABLE IF EXISTS notification_deliveries`);
+      raw.exec(/*sql*/ `DROP TABLE IF EXISTS notification_decisions`);
+      raw.exec(/*sql*/ `DROP TABLE IF EXISTS notification_events`);
+      raw.exec(/*sql*/ `DROP TABLE IF EXISTS notification_preferences`);
+
+      raw.query(
+        `INSERT OR IGNORE INTO memory_checkpoints (key, value, updated_at) VALUES (?, '1', ?)`,
+      ).run(checkpointKey, Date.now());
+
+      raw.exec('COMMIT');
+    } catch (e) {
+      try { raw.exec('ROLLBACK'); } catch { /* no active transaction */ }
+      throw e;
+    }
+  } else {
+    // No old schema detected (fresh install or already migrated).
+    // Still clean up notification_preferences if it exists, since we want
+    // to ensure it's removed regardless.
+    try {
+      raw.exec('BEGIN');
+
+      raw.exec(/*sql*/ `DROP TABLE IF EXISTS notification_preferences`);
+
+      raw.query(
+        `INSERT OR IGNORE INTO memory_checkpoints (key, value, updated_at) VALUES (?, '1', ?)`,
+      ).run(checkpointKey, Date.now());
+
+      raw.exec('COMMIT');
+    } catch (e) {
+      try { raw.exec('ROLLBACK'); } catch { /* no active transaction */ }
+      throw e;
+    }
+  }
+}

package/src/memory/migrations/index.ts

@@ -22,3 +22,4 @@ export { migrateDropActiveSearchIndex } from './015-drop-active-search-index.js'
 export { migrateMemorySegmentsIndexes } from './016-memory-segments-indexes.js';
 export { migrateMemoryItemsIndexes } from './017-memory-items-indexes.js';
 export { migrateRemainingTableIndexes } from './018-remaining-table-indexes.js';
+export { migrateNotificationTablesSchema } from './019-notification-tables-schema-migration.js';

package/src/memory/migrations/registry.ts

@@ -69,6 +69,11 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     version: 9,
     description: 'Drop old idx_memory_items_active_search so it can be recreated with updated covering columns',
   },
+  {
+    key: 'migration_notification_tables_schema_v1',
+    version: 10,
+    description: 'Drop legacy enum-based notification tables so they can be recreated with the new signal-contract schema',
+  },
 ];
 
 export interface MigrationValidationResult {

package/src/memory/schema-migration.ts

@@ -19,6 +19,7 @@ export {
   migrateGuardianActionTables,
   migrateBackfillInboxThreadStateFromBindings,
   migrateDropActiveSearchIndex,
+  migrateNotificationTablesSchema,
   migrateMemorySegmentsIndexes,
   migrateMemoryItemsIndexes,
   migrateRemainingTableIndexes,

package/src/memory/schema.ts

@@ -64,7 +64,6 @@ export const memorySegments = sqliteTable('memory_segments', {
   updatedAt: integer('updated_at').notNull(),
 }, (table) => [
   index('idx_memory_segments_scope_id').on(table.scopeId),
-  index('idx_memory_segments_conversation_id').on(table.conversationId),
 ]);
 
 export const memoryItems = sqliteTable('memory_items', {
@@ -901,3 +900,62 @@ export const assistantInboxThreadState = sqliteTable('assistant_inbox_thread_sta
   createdAt: integer('created_at').notNull(),
   updatedAt: integer('updated_at').notNull(),
 });
+
+// ── Notification System ──────────────────────────────────────────────
+
+export const notificationEvents = sqliteTable('notification_events', {
+  id: text('id').primaryKey(),
+  assistantId: text('assistant_id').notNull(),
+  sourceEventName: text('source_event_name').notNull(),
+  sourceChannel: text('source_channel').notNull(),
+  sourceSessionId: text('source_session_id').notNull(),
+  attentionHintsJson: text('attention_hints_json').notNull().default('{}'),
+  payloadJson: text('payload_json').notNull().default('{}'),
+  dedupeKey: text('dedupe_key'),
+  createdAt: integer('created_at').notNull(),
+  updatedAt: integer('updated_at').notNull(),
+});
+
+export const notificationDecisions = sqliteTable('notification_decisions', {
+  id: text('id').primaryKey(),
+  notificationEventId: text('notification_event_id')
+    .notNull()
+    .references(() => notificationEvents.id, { onDelete: 'cascade' }),
+  shouldNotify: integer('should_notify').notNull(),
+  selectedChannels: text('selected_channels').notNull().default('[]'),
+  reasoningSummary: text('reasoning_summary').notNull(),
+  confidence: real('confidence').notNull(),
+  fallbackUsed: integer('fallback_used').notNull().default(0),
+  promptVersion: text('prompt_version'),
+  validationResults: text('validation_results'),
+  createdAt: integer('created_at').notNull(),
+});
+
+export const notificationPreferences = sqliteTable('notification_preferences', {
+  id: text('id').primaryKey(),
+  assistantId: text('assistant_id').notNull(),
+  preferenceText: text('preference_text').notNull(),
+  appliesWhenJson: text('applies_when_json').notNull().default('{}'),
+  priority: integer('priority').notNull().default(0),
+  createdAt: integer('created_at').notNull(),
+  updatedAt: integer('updated_at').notNull(),
+});
+
+export const notificationDeliveries = sqliteTable('notification_deliveries', {
+  id: text('id').primaryKey(),
+  notificationDecisionId: text('notification_decision_id')
+    .notNull()
+    .references(() => notificationDecisions.id, { onDelete: 'cascade' }),
+  assistantId: text('assistant_id').notNull(),
+  channel: text('channel').notNull(),
+  destination: text('destination').notNull(),
+  status: text('status').notNull().default('pending'),
+  attempt: integer('attempt').notNull().default(1),
+  renderedTitle: text('rendered_title'),
+  renderedBody: text('rendered_body'),
+  errorCode: text('error_code'),
+  errorMessage: text('error_message'),
+  sentAt: integer('sent_at'),
+  createdAt: integer('created_at').notNull(),
+  updatedAt: integer('updated_at').notNull(),
+});

package/src/notifications/README.md

@@ -0,0 +1,134 @@
+# Notification System
+
+Signal-driven notification architecture where producers emit free-form events and an LLM-backed decision engine determines whether, where, and how to notify the user.
+
+## Lifecycle
+
+```
+Producer → NotificationSignal → Decision Engine (LLM) → Deterministic Checks → Broadcaster → Adapters → Delivery
+                                       ↑
+                               Preference Summary
+```
+
+### 1. Signal
+
+A producer calls `emitNotificationSignal()` with a free-form event name, attention hints (urgency, requiresAction, deadlineAt), and a context payload. The signal is persisted as a `notification_events` row.
+
+### 2. Decision
+
+The decision engine (`decision-engine.ts`) sends the signal to an LLM (configured via `notifications.decisionModel`) along with available channels and the user's preference summary. The LLM responds with a structured decision: whether to notify, which channels, rendered copy per channel, and a deduplication key.
+
+When the LLM is unavailable or returns invalid output, a deterministic fallback fires: high-urgency + requires-action signals notify on all channels; everything else is suppressed.
+
+### 3. Deterministic Checks
+
+Hard invariants that the LLM cannot override (`deterministic-checks.ts`):
+
+- **Schema validity** -- fail-closed if the decision is malformed
+- **Source-active suppression** -- if the user is already viewing the source context, suppress
+- **Channel availability** -- at least one selected channel must be connected
+- **Deduplication** -- same `dedupeKey` within the dedupe window (1 hour default) is suppressed
+
+### 4. Dispatch
+
+`runtime-dispatch.ts` handles three early-exit cases (shouldNotify=false, shadow mode, no channels), then delegates to the broadcaster.
+
+### 5. Broadcast and Delivery
+
+The broadcaster (`broadcaster.ts`) iterates over selected channels, resolves destinations via `destination-resolver.ts`, pulls rendered copy from the decision (falling back to `copy-composer.ts` templates), and dispatches through channel adapters. Each delivery attempt is recorded in `notification_deliveries`.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `emit-signal.ts` | Single entry point for producers; orchestrates the full pipeline |
+| `signal.ts` | `NotificationSignal` and `AttentionHints` type definitions |
+| `types.ts` | Channel adapter interfaces, delivery types, decision output contract |
+| `decision-engine.ts` | LLM-based routing with forced tool_choice; deterministic fallback |
+| `deterministic-checks.ts` | Pre-send gate checks (dedupe, source-active, channel availability) |
+| `runtime-dispatch.ts` | Dispatch gating (shadow mode, no-op decisions) |
+| `broadcaster.ts` | Fan-out to channel adapters with delivery audit trail |
+| `copy-composer.ts` | Template-based fallback copy when LLM copy is unavailable |
+| `destination-resolver.ts` | Resolves per-channel endpoints (macOS IPC, Telegram chat ID) |
+| `adapters/macos.ts` | macOS adapter -- broadcasts `notification_intent` via IPC |
+| `adapters/telegram.ts` | Telegram adapter -- POSTs to gateway `/deliver/telegram` |
+| `preference-extractor.ts` | Detects notification preferences in conversation messages |
+| `preference-summary.ts` | Builds preference context string for the decision engine prompt |
+| `preferences-store.ts` | CRUD for `notification_preferences` table |
+| `events-store.ts` | CRUD for `notification_events` table |
+| `decisions-store.ts` | CRUD for `notification_decisions` table |
+| `deliveries-store.ts` | CRUD for `notification_deliveries` table |
+
+## How to Add a New Notification Producer
+
+1. Import `emitNotificationSignal` from `./emit-signal.js`.
+2. Call it with the signal parameters:
+
+```ts
+import { emitNotificationSignal } from '../notifications/emit-signal.js';
+
+await emitNotificationSignal({
+  sourceEventName: 'your_event_name',
+  sourceChannel: 'scheduler',       // where the event originated
+  sourceSessionId: sessionId,
+  attentionHints: {
+    requiresAction: true,
+    urgency: 'high',
+    isAsyncBackground: false,
+    visibleInSourceNow: false,
+  },
+  contextPayload: { /* arbitrary data for the decision engine */ },
+});
+```
+
+3. Optionally add a fallback copy template in `copy-composer.ts` keyed by your `sourceEventName`. Without a template, the generic fallback produces a human-readable version of the event name.
+
+The call is fire-and-forget safe -- errors are caught and logged internally.
+
+## Audit Trail
+
+Three SQLite tables form the audit chain:
+
+- **`notification_events`** -- every signal that entered the pipeline, with attention hints and context payload
+- **`notification_decisions`** -- the routing decision for each event (shouldNotify, selectedChannels, reasoning, confidence, whether fallback was used)
+- **`notification_deliveries`** -- per-channel delivery attempts with status (pending/sent/failed/skipped), rendered copy, and error details
+
+Query examples:
+
+```sql
+-- Recent decisions that resulted in notifications
+SELECT e.source_event_name, d.should_notify, d.selected_channels, d.reasoning_summary
+FROM notification_decisions d
+JOIN notification_events e ON d.notification_event_id = e.id
+WHERE d.should_notify = 1
+ORDER BY d.created_at DESC
+LIMIT 20;
+
+-- Failed deliveries
+SELECT d.channel, d.error_message, d.rendered_title
+FROM notification_deliveries d
+WHERE d.status = 'failed'
+ORDER BY d.created_at DESC;
+```
+
+## Conversational Preferences
+
+Users express notification preferences in natural language during conversations (e.g., "Use Telegram for urgent alerts", "Mute notifications after 10pm"). The system:
+
+1. **Detects** preferences via `preference-extractor.ts` -- an LLM call that runs on each user message in `session-process.ts`
+2. **Stores** them in `notification_preferences` with structured conditions (`appliesWhen`: timeRange, channels, urgencyLevels, contexts) and a priority level (0=default, 1=override, 2=critical)
+3. **Summarizes** them at decision time via `preference-summary.ts`, which builds a compact text block injected into the decision engine's system prompt
+
+Preferences are sanitized against prompt injection (angle brackets replaced with harmless unicode equivalents).
+
+## Configuration
+
+All settings live under the `notifications` key in `config.json`:
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `notifications.enabled` | boolean | `false` | Master switch for the notification pipeline |
+| `notifications.shadowMode` | boolean | `true` | When true, decisions are logged but not dispatched |
+| `notifications.decisionModel` | string | `"claude-haiku-4-5-20251001"` | Model used for both the decision engine and preference extraction |
+
+Shadow mode is useful for validating decision quality before enabling live delivery. The audit trail (events + decisions) is written regardless of shadow mode.

package/src/notifications/adapters/macos.ts

@@ -0,0 +1,55 @@
+/**
+ * macOS channel adapter — delivers notifications to connected desktop
+ * clients via the daemon's IPC broadcast mechanism.
+ *
+ * The adapter broadcasts a `notification_intent` message that the macOS
+ * client can use to display a native notification (e.g. NSUserNotification
+ * or UNUserNotificationCenter).
+ */
+
+import { getLogger } from '../../util/logger.js';
+import type { ServerMessage } from '../../daemon/ipc-contract.js';
+import type {
+  NotificationChannel,
+  ChannelAdapter,
+  ChannelDeliveryPayload,
+  ChannelDestination,
+  DeliveryResult,
+} from '../types.js';
+
+const log = getLogger('notif-adapter-macos');
+
+export type BroadcastFn = (msg: ServerMessage) => void;
+
+export class MacOSAdapter implements ChannelAdapter {
+  readonly channel: NotificationChannel = 'macos';
+
+  private broadcast: BroadcastFn;
+
+  constructor(broadcast: BroadcastFn) {
+    this.broadcast = broadcast;
+  }
+
+  async send(payload: ChannelDeliveryPayload, _destination: ChannelDestination): Promise<DeliveryResult> {
+    try {
+      this.broadcast({
+        type: 'notification_intent',
+        sourceEventName: payload.sourceEventName,
+        title: payload.copy.title,
+        body: payload.copy.body,
+        deepLinkMetadata: payload.deepLinkTarget,
+      } as ServerMessage);
+
+      log.info(
+        { sourceEventName: payload.sourceEventName, title: payload.copy.title },
+        'macOS notification intent broadcast',
+      );
+
+      return { success: true };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.error({ err, sourceEventName: payload.sourceEventName }, 'Failed to broadcast macOS notification intent');
+      return { success: false, error: message };
+    }
+  }
+}

package/src/notifications/adapters/telegram.ts

@@ -0,0 +1,65 @@
+/**
+ * Telegram channel adapter — delivers notifications to Telegram chats
+ * via the gateway's channel-reply endpoint.
+ *
+ * Follows the same delivery pattern used by guardian-dispatch: POST to
+ * the gateway's `/deliver/telegram` endpoint with a chat ID and text
+ * payload. The gateway forwards the message to the Telegram Bot API.
+ */
+
+import { getLogger } from '../../util/logger.js';
+import { getGatewayInternalBaseUrl } from '../../config/env.js';
+import { deliverChannelReply } from '../../runtime/gateway-client.js';
+import { readHttpToken } from '../../util/platform.js';
+import type {
+  NotificationChannel,
+  ChannelAdapter,
+  ChannelDeliveryPayload,
+  ChannelDestination,
+  DeliveryResult,
+} from '../types.js';
+
+const log = getLogger('notif-adapter-telegram');
+
+export class TelegramAdapter implements ChannelAdapter {
+  readonly channel: NotificationChannel = 'telegram';
+
+  async send(payload: ChannelDeliveryPayload, destination: ChannelDestination): Promise<DeliveryResult> {
+    const chatId = destination.endpoint;
+    if (!chatId) {
+      log.warn({ sourceEventName: payload.sourceEventName }, 'Telegram destination has no chat ID — skipping');
+      return { success: false, error: 'No chat ID configured for Telegram destination' };
+    }
+
+    const gatewayBase = getGatewayInternalBaseUrl();
+    const deliverUrl = `${gatewayBase}/deliver/telegram`;
+
+    // Format copy for Telegram as plain text (no parse_mode set on gateway side)
+    let messageText = payload.copy.title + '\n\n' + payload.copy.body;
+    if (payload.copy.threadTitle) {
+      messageText += '\n\nThread: ' + payload.copy.threadTitle;
+    }
+
+    try {
+      await deliverChannelReply(
+        deliverUrl,
+        { chatId, text: messageText },
+        readHttpToken() ?? undefined,
+      );
+
+      log.info(
+        { sourceEventName: payload.sourceEventName, chatId },
+        'Telegram notification delivered',
+      );
+
+      return { success: true };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.error(
+        { err, sourceEventName: payload.sourceEventName, chatId },
+        'Failed to deliver Telegram notification',
+      );
+      return { success: false, error: message };
+    }
+  }
+}