@vellumai/assistant 0.3.7 → 0.3.9

package/src/notifications/preferences-store.ts

@@ -0,0 +1,142 @@
+/**
+ * CRUD operations for notification preferences.
+ *
+ * Each row stores a natural-language notification preference expressed by
+ * the user (e.g. "Use Telegram for urgent alerts"), along with structured
+ * conditions for when the preference applies and a priority for conflict
+ * resolution.
+ */
+
+import { and, desc, eq } from 'drizzle-orm';
+import { v4 as uuid } from 'uuid';
+import { getDb } from '../memory/db.js';
+import { notificationPreferences } from '../memory/schema.js';
+
+// ── Row type ────────────────────────────────────────────────────────────
+
+export interface NotificationPreferenceRow {
+  id: string;
+  assistantId: string;
+  preferenceText: string;
+  appliesWhenJson: string; // serialised JSON
+  priority: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+function rowToPreference(row: typeof notificationPreferences.$inferSelect): NotificationPreferenceRow {
+  return {
+    id: row.id,
+    assistantId: row.assistantId,
+    preferenceText: row.preferenceText,
+    appliesWhenJson: row.appliesWhenJson,
+    priority: row.priority,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+// ── Structured conditions type ──────────────────────────────────────────
+
+export interface AppliesWhenConditions {
+  timeRange?: { after?: string; before?: string }; // e.g. "22:00", "06:00"
+  channels?: string[];        // e.g. ["telegram", "macos"]
+  urgencyLevels?: string[];   // e.g. ["high", "critical"]
+  contexts?: string[];        // e.g. ["work_calls", "meetings"]
+  [key: string]: unknown;
+}
+
+// ── Create ──────────────────────────────────────────────────────────────
+
+export interface CreatePreferenceParams {
+  assistantId: string;
+  preferenceText: string;
+  appliesWhen?: AppliesWhenConditions;
+  priority?: number;
+}
+
+export function createPreference(params: CreatePreferenceParams): NotificationPreferenceRow {
+  const db = getDb();
+  const now = Date.now();
+
+  const row = {
+    id: uuid(),
+    assistantId: params.assistantId,
+    preferenceText: params.preferenceText,
+    appliesWhenJson: JSON.stringify(params.appliesWhen ?? {}),
+    priority: params.priority ?? 0,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  db.insert(notificationPreferences).values(row).run();
+
+  return row;
+}
+
+// ── List ────────────────────────────────────────────────────────────────
+
+export function listPreferences(assistantId: string): NotificationPreferenceRow[] {
+  const db = getDb();
+
+  const rows = db
+    .select()
+    .from(notificationPreferences)
+    .where(eq(notificationPreferences.assistantId, assistantId))
+    .orderBy(desc(notificationPreferences.priority))
+    .all();
+
+  return rows.map(rowToPreference);
+}
+
+// ── Update ──────────────────────────────────────────────────────────────
+
+export interface UpdatePreferenceParams {
+  preferenceText?: string;
+  appliesWhen?: AppliesWhenConditions;
+  priority?: number;
+}
+
+export function updatePreference(id: string, params: UpdatePreferenceParams): boolean {
+  const db = getDb();
+  const now = Date.now();
+
+  const updates: Record<string, unknown> = { updatedAt: now };
+  if (params.preferenceText !== undefined) updates.preferenceText = params.preferenceText;
+  if (params.appliesWhen !== undefined) updates.appliesWhenJson = JSON.stringify(params.appliesWhen);
+  if (params.priority !== undefined) updates.priority = params.priority;
+
+  const result = db
+    .update(notificationPreferences)
+    .set(updates)
+    .where(eq(notificationPreferences.id, id))
+    .run() as unknown as { changes?: number };
+
+  return (result.changes ?? 0) > 0;
+}
+
+// ── Delete ──────────────────────────────────────────────────────────────
+
+export function deletePreference(id: string): boolean {
+  const db = getDb();
+
+  const result = db
+    .delete(notificationPreferences)
+    .where(eq(notificationPreferences.id, id))
+    .run() as unknown as { changes?: number };
+
+  return (result.changes ?? 0) > 0;
+}
+
+// ── Get by ID ───────────────────────────────────────────────────────────
+
+export function getPreferenceById(id: string): NotificationPreferenceRow | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(notificationPreferences)
+    .where(eq(notificationPreferences.id, id))
+    .get();
+  if (!row) return null;
+  return rowToPreference(row);
+}

package/src/notifications/runtime-dispatch.ts

@@ -0,0 +1,100 @@
+/**
+ * In-loop dispatch helper that wires the decision engine output to the
+ * broadcaster/adapters for end-to-end signal → decision → dispatch → delivery.
+ *
+ * Not a standalone service — called inline from the notification processing
+ * loop after the decision engine and deterministic checks have run.
+ */
+
+import { getConfig } from '../config/loader.js';
+import { getLogger } from '../util/logger.js';
+import type { NotificationBroadcaster } from './broadcaster.js';
+import type { NotificationSignal } from './signal.js';
+import type { NotificationDecision, NotificationDeliveryResult } from './types.js';
+
+const log = getLogger('notification-dispatch');
+
+export interface DispatchResult {
+  dispatched: boolean;
+  reason: string;
+  deliveryResults: NotificationDeliveryResult[];
+}
+
+/**
+ * Dispatch a notification decision through the broadcaster.
+ *
+ * Handles three early-exit cases before delegating to the broadcaster:
+ * 1. shouldNotify === false — the decision says not to notify
+ * 2. Shadow mode — decisions are logged but not actually dispatched
+ * 3. No selected channels — nothing to dispatch
+ */
+export async function dispatchDecision(
+  signal: NotificationSignal,
+  decision: NotificationDecision,
+  broadcaster: NotificationBroadcaster,
+): Promise<DispatchResult> {
+  // No-op when the decision engine says not to notify
+  if (!decision.shouldNotify) {
+    log.info(
+      { signalId: signal.signalId, reason: decision.reasoningSummary },
+      'Decision: do not notify',
+    );
+    return {
+      dispatched: false,
+      reason: 'Decision: shouldNotify=false',
+      deliveryResults: [],
+    };
+  }
+
+  // Shadow mode: log the decision but skip actual delivery
+  const config = getConfig();
+  if (config.notifications.shadowMode) {
+    log.info(
+      {
+        signalId: signal.signalId,
+        channels: decision.selectedChannels,
+        confidence: decision.confidence,
+        fallbackUsed: decision.fallbackUsed,
+      },
+      'Shadow mode: skipping dispatch (decision logged only)',
+    );
+    return {
+      dispatched: false,
+      reason: 'Shadow mode enabled — dispatch skipped',
+      deliveryResults: [],
+    };
+  }
+
+  // Guard against empty channel list
+  if (decision.selectedChannels.length === 0) {
+    log.info(
+      { signalId: signal.signalId },
+      'No channels selected in decision — nothing to dispatch',
+    );
+    return {
+      dispatched: false,
+      reason: 'No channels selected',
+      deliveryResults: [],
+    };
+  }
+
+  // Dispatch through the broadcaster
+  const deliveryResults = await broadcaster.broadcastDecision(signal, decision);
+
+  const sentCount = deliveryResults.filter((r) => r.status === 'sent').length;
+  log.info(
+    {
+      signalId: signal.signalId,
+      channels: decision.selectedChannels,
+      sentCount,
+      totalAttempted: deliveryResults.length,
+    },
+    'Dispatch complete',
+  );
+
+  return {
+    dispatched: true,
+    reason: `Dispatched to ${sentCount}/${deliveryResults.length} channels`,
+    deliveryResults,
+  };
+}

package/src/notifications/signal.ts

@@ -0,0 +1,24 @@
+/**
+ * NotificationSignal -- the flexible input from producers.
+ * Uses free-form event names and structured attention hints that let the
+ * decision engine route contextually.
+ */
+
+export interface AttentionHints {
+  requiresAction: boolean;
+  urgency: 'low' | 'medium' | 'high';
+  deadlineAt?: number; // epoch ms
+  isAsyncBackground: boolean;
+  visibleInSourceNow: boolean;
+}
+
+export interface NotificationSignal {
+  signalId: string;
+  assistantId: string;
+  createdAt: number; // epoch ms
+  sourceChannel: string; // free-form: 'macos', 'telegram', 'voice', 'scheduler', etc.
+  sourceSessionId: string;
+  sourceEventName: string; // free-form: 'reminder_fired', 'schedule_complete', 'guardian_question', etc.
+  contextPayload: Record<string, unknown>;
+  attentionHints: AttentionHints;
+}

package/src/notifications/types.ts

@@ -0,0 +1,75 @@
+/**
+ * Core domain types for the unified notification system.
+ *
+ * Defines the channel-adapter interfaces that the broadcaster and adapters
+ * depend on, plus the decision engine output contract.
+ */
+
+export type NotificationChannel = 'macos' | 'telegram';
+
+export type NotificationDeliveryStatus = 'pending' | 'sent' | 'failed' | 'skipped';
+
+/** Result of attempting to deliver a notification to a single channel. */
+export interface NotificationDeliveryResult {
+  channel: NotificationChannel;
+  destination: string;
+  status: NotificationDeliveryStatus;
+  errorCode?: string;
+  errorMessage?: string;
+  sentAt?: number;
+}
+
+// -- Channel adapter interfaces -----------------------------------------------
+
+/** Result returned by a channel adapter after attempting to send. */
+export interface DeliveryResult {
+  success: boolean;
+  error?: string;
+}
+
+/** Resolved destination for a specific channel. */
+export interface ChannelDestination {
+  channel: NotificationChannel;
+  endpoint?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Delivery payload assembled from the decision engine's rendered copy
+ * plus contextual fields the adapters need for formatting and routing.
+ */
+export interface ChannelDeliveryPayload {
+  sourceEventName: string;
+  copy: RenderedChannelCopy;
+  deepLinkTarget?: Record<string, unknown>;
+}
+
+/** Interface that each channel adapter must implement. */
+export interface ChannelAdapter {
+  channel: NotificationChannel;
+  send(payload: ChannelDeliveryPayload, destination: ChannelDestination): Promise<DeliveryResult>;
+}
+
+// -- Decision engine output ---------------------------------------------------
+
+/** Rendered notification copy for a single channel. */
+export interface RenderedChannelCopy {
+  title: string;
+  body: string;
+  threadTitle?: string;
+  threadSeedMessage?: string;
+}
+
+/** Output produced by the notification decision engine for a given signal. */
+export interface NotificationDecision {
+  shouldNotify: boolean;
+  selectedChannels: NotificationChannel[];
+  reasoningSummary: string;
+  renderedCopy: Partial<Record<NotificationChannel, RenderedChannelCopy>>;
+  deepLinkTarget?: Record<string, unknown>;
+  dedupeKey: string;
+  confidence: number;
+  fallbackUsed: boolean;
+  /** UUID of the persisted decision row (set after persistence in the decision engine). */
+  persistedDecisionId?: string;
+}

package/src/runtime/http-server.ts

@@ -35,6 +35,11 @@ import {
   handleRunSecret,
   handleAddTrustRule,
 } from './routes/run-routes.js';
+import {
+  handleConfirm,
+  handleSecret,
+  handleTrustRule,
+} from './routes/approval-routes.js';
 import {
   handleDeleteConversation,
   handleChannelInbound,
@@ -121,6 +126,7 @@ export type {
   RuntimeAttachmentMetadata,
   ApprovalCopyGenerator,
   ApprovalConversationGenerator,
+  SendMessageDeps,
 } from './http-types.js';
 
 import type {
@@ -129,6 +135,7 @@ import type {
   RuntimeHttpServerOptions,
   ApprovalCopyGenerator,
   ApprovalConversationGenerator,
+  SendMessageDeps,
 } from './http-types.js';
 
 const log = getLogger('runtime-http');
@@ -156,6 +163,7 @@ export class RuntimeHttpServer {
   private sweepInProgress = false;
   private pairingStore = new PairingStore();
   private pairingBroadcast?: (msg: ServerMessage) => void;
+  private sendMessageDeps?: SendMessageDeps;
 
   constructor(options: RuntimeHttpServerOptions = {}) {
     this.port = options.port ?? DEFAULT_PORT;
@@ -167,6 +175,7 @@ export class RuntimeHttpServer {
     this.approvalCopyGenerator = options.approvalCopyGenerator;
     this.approvalConversationGenerator = options.approvalConversationGenerator;
     this.interfacesDir = options.interfacesDir ?? null;
+    this.sendMessageDeps = options.sendMessageDeps;
   }
 
   /** The port the server is actually listening on (resolved after start). */
@@ -558,9 +567,15 @@ export class RuntimeHttpServer {
         return await handleSendMessage(req, {
           processMessage: this.processMessage,
           persistAndProcessMessage: this.persistAndProcessMessage,
+          sendMessageDeps: this.sendMessageDeps,
         });
       }
 
+      // Standalone approval endpoints — keyed by requestId, orthogonal to message sending
+      if (endpoint === 'confirm' && req.method === 'POST') return await handleConfirm(req);
+      if (endpoint === 'secret' && req.method === 'POST') return await handleSecret(req);
+      if (endpoint === 'trust-rules' && req.method === 'POST') return await handleTrustRule(req);
+
       if (endpoint === 'attachments' && req.method === 'POST') return await handleUploadAttachment(req);
       if (endpoint === 'attachments' && req.method === 'DELETE') return await handleDeleteAttachment(req);
 

package/src/runtime/http-types.ts

@@ -5,6 +5,8 @@ import type { ChannelId } from '../channels/types.js';
 import type { RunOrchestrator } from './run-orchestrator.js';
 import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
 import type { ApprovalMessageContext, ComposeApprovalMessageGenerativeOptions } from './approval-message-composer.js';
+import type { Session } from '../daemon/session.js';
+import type { AssistantEventHub } from './assistant-event-hub.js';
 
 /**
  * Daemon-injected function that generates approval copy using a provider.
@@ -84,6 +86,24 @@ export type NonBlockingMessageProcessor = (
   sourceChannel?: ChannelId,
 ) => Promise<{ messageId: string }>;
 
+/**
+ * Dependencies for the POST /v1/messages handler.
+ *
+ * The handler needs direct access to the session so it can check busy state,
+ * persist user messages, fire the agent loop, or queue messages when busy.
+ * Hub publishing wires outbound events to the SSE stream.
+ */
+export interface SendMessageDeps {
+  getOrCreateSession: (conversationId: string) => Promise<Session>;
+  assistantEventHub: AssistantEventHub;
+  resolveAttachments: (attachmentIds: string[]) => Array<{
+    id: string;
+    filename: string;
+    mimeType: string;
+    data: string;
+  }>;
+}
+
 export interface RuntimeHttpServerOptions {
   port?: number;
   /** Hostname / IP to bind to. Defaults to '127.0.0.1' (loopback-only). */
@@ -101,6 +121,8 @@ export interface RuntimeHttpServerOptions {
   approvalCopyGenerator?: ApprovalCopyGenerator;
   /** Daemon-injected generator for conversational approval flow (provider-backed). */
   approvalConversationGenerator?: ApprovalConversationGenerator;
+  /** Dependencies for the POST /v1/messages queue-if-busy handler. */
+  sendMessageDeps?: SendMessageDeps;
 }
 
 export interface RuntimeAttachmentMetadata {

package/src/runtime/pending-interactions.ts

@@ -0,0 +1,73 @@
+/**
+ * In-memory tracker that maps requestId to session info for pending
+ * confirmation and secret interactions.
+ *
+ * When the agent loop emits a confirmation_request or secret_request,
+ * the onEvent callback registers the interaction here. Standalone HTTP
+ * endpoints (/v1/confirm, /v1/secret, /v1/trust-rules) look up the
+ * session from this tracker to resolve the interaction.
+ */
+
+import type { Session } from '../daemon/session.js';
+
+export interface ConfirmationDetails {
+  toolName: string;
+  input: Record<string, unknown>;
+  riskLevel: string;
+  executionTarget?: 'sandbox' | 'host';
+  allowlistOptions: Array<{ label: string; description: string; pattern: string }>;
+  scopeOptions: Array<{ label: string; scope: string }>;
+  persistentDecisionsAllowed?: boolean;
+}
+
+export interface PendingInteraction {
+  session: Session;
+  conversationId: string;
+  kind: 'confirmation' | 'secret';
+  confirmationDetails?: ConfirmationDetails;
+}
+
+const pending = new Map<string, PendingInteraction>();
+
+export function register(requestId: string, interaction: PendingInteraction): void {
+  pending.set(requestId, interaction);
+}
+
+/**
+ * Remove and return the pending interaction for the given requestId.
+ * Returns undefined if no interaction is registered.
+ */
+export function resolve(requestId: string): PendingInteraction | undefined {
+  const interaction = pending.get(requestId);
+  if (interaction) {
+    pending.delete(requestId);
+  }
+  return interaction;
+}
+
+/**
+ * Return the pending interaction without removing it.
+ * Used by trust-rule endpoint which doesn't resolve the confirmation itself.
+ */
+export function get(requestId: string): PendingInteraction | undefined {
+  return pending.get(requestId);
+}
+
+/**
+ * Return all pending interactions for a given conversation.
+ * Needed by channel approval migration (PR 3).
+ */
+export function getByConversation(conversationId: string): Array<{ requestId: string } & PendingInteraction> {
+  const results: Array<{ requestId: string } & PendingInteraction> = [];
+  for (const [requestId, interaction] of pending) {
+    if (interaction.conversationId === conversationId) {
+      results.push({ requestId, ...interaction });
+    }
+  }
+  return results;
+}
+
+/** Clear all pending interactions. Useful for testing. */
+export function clear(): void {
+  pending.clear();
+}

package/src/runtime/routes/approval-routes.ts

@@ -0,0 +1,179 @@
+/**
+ * Route handlers for standalone approval endpoints.
+ *
+ * These endpoints resolve pending confirmations, secrets, and trust rules
+ * by requestId — orthogonal to message sending.
+ */
+import * as pendingInteractions from '../pending-interactions.js';
+import { addRule } from '../../permissions/trust-store.js';
+import { getTool } from '../../tools/registry.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('approval-routes');
+
+/**
+ * POST /v1/confirm — resolve a pending confirmation by requestId.
+ */
+export async function handleConfirm(req: Request): Promise<Response> {
+  const body = await req.json() as {
+    requestId?: string;
+    decision?: string;
+  };
+
+  const { requestId, decision } = body;
+
+  if (!requestId || typeof requestId !== 'string') {
+    return Response.json({ error: 'requestId is required' }, { status: 400 });
+  }
+
+  if (decision !== 'allow' && decision !== 'deny') {
+    return Response.json(
+      { error: 'decision must be "allow" or "deny"' },
+      { status: 400 },
+    );
+  }
+
+  const interaction = pendingInteractions.resolve(requestId);
+  if (!interaction) {
+    return Response.json(
+      { error: 'No pending interaction found for this requestId' },
+      { status: 404 },
+    );
+  }
+
+  interaction.session.handleConfirmationResponse(requestId, decision);
+  return Response.json({ accepted: true });
+}
+
+/**
+ * POST /v1/secret — resolve a pending secret request by requestId.
+ */
+export async function handleSecret(req: Request): Promise<Response> {
+  const body = await req.json() as {
+    requestId?: string;
+    value?: string;
+    delivery?: string;
+  };
+
+  const { requestId, value, delivery } = body;
+
+  if (!requestId || typeof requestId !== 'string') {
+    return Response.json({ error: 'requestId is required' }, { status: 400 });
+  }
+
+  if (delivery !== undefined && delivery !== 'store' && delivery !== 'transient_send') {
+    return Response.json(
+      { error: 'delivery must be "store" or "transient_send"' },
+      { status: 400 },
+    );
+  }
+
+  const interaction = pendingInteractions.resolve(requestId);
+  if (!interaction) {
+    return Response.json(
+      { error: 'No pending interaction found for this requestId' },
+      { status: 404 },
+    );
+  }
+
+  interaction.session.handleSecretResponse(
+    requestId,
+    value,
+    delivery as 'store' | 'transient_send' | undefined,
+  );
+  return Response.json({ accepted: true });
+}
+
+/**
+ * POST /v1/trust-rules — add a trust rule for a pending confirmation.
+ *
+ * Does NOT resolve the confirmation itself (the client still needs to
+ * POST /v1/confirm to approve/deny). Validates the pattern and scope
+ * against the server-provided allowlist options from the original
+ * confirmation_request.
+ */
+export async function handleTrustRule(req: Request): Promise<Response> {
+  const body = await req.json() as {
+    requestId?: string;
+    pattern?: string;
+    scope?: string;
+    decision?: string;
+  };
+
+  const { requestId, pattern, scope, decision } = body;
+
+  if (!requestId || typeof requestId !== 'string') {
+    return Response.json({ error: 'requestId is required' }, { status: 400 });
+  }
+
+  if (!pattern || typeof pattern !== 'string') {
+    return Response.json({ error: 'pattern is required' }, { status: 400 });
+  }
+
+  if (!scope || typeof scope !== 'string') {
+    return Response.json({ error: 'scope is required' }, { status: 400 });
+  }
+
+  if (decision !== 'allow' && decision !== 'deny') {
+    return Response.json({ error: 'decision must be "allow" or "deny"' }, { status: 400 });
+  }
+
+  // Look up without removing — trust rule doesn't resolve the confirmation
+  const interaction = pendingInteractions.get(requestId);
+  if (!interaction) {
+    return Response.json(
+      { error: 'No pending interaction found for this requestId' },
+      { status: 404 },
+    );
+  }
+
+  if (!interaction.confirmationDetails) {
+    return Response.json(
+      { error: 'No confirmation details available for this request' },
+      { status: 409 },
+    );
+  }
+
+  const confirmation = interaction.confirmationDetails;
+
+  if (confirmation.persistentDecisionsAllowed === false) {
+    return Response.json(
+      { error: 'Persistent trust rules are not allowed for this tool invocation' },
+      { status: 403 },
+    );
+  }
+
+  // Validate pattern against server-provided allowlist options
+  const validPatterns = (confirmation.allowlistOptions ?? []).map((o) => o.pattern);
+  if (!validPatterns.includes(pattern)) {
+    return Response.json(
+      { error: 'pattern does not match any server-provided allowlist option' },
+      { status: 403 },
+    );
+  }
+
+  // Validate scope against server-provided scope options
+  const validScopes = (confirmation.scopeOptions ?? []).map((o) => o.scope);
+  if (!validScopes.includes(scope)) {
+    return Response.json(
+      { error: 'scope does not match any server-provided scope option' },
+      { status: 403 },
+    );
+  }
+
+  try {
+    const tool = getTool(confirmation.toolName);
+    const executionTarget = tool?.origin === 'skill' ? confirmation.executionTarget : undefined;
+    addRule(confirmation.toolName, pattern, scope, decision, undefined, {
+      executionTarget,
+    });
+    log.info(
+      { tool: confirmation.toolName, pattern, scope, decision, requestId },
+      'Trust rule added via HTTP (bound to pending confirmation)',
+    );
+    return Response.json({ accepted: true });
+  } catch (err) {
+    log.error({ err }, 'Failed to add trust rule');
+    return Response.json({ error: 'Failed to add trust rule' }, { status: 500 });
+  }
+}