vellum 0.2.1 → 0.2.7

package/src/daemon/session-messaging.ts

@@ -0,0 +1,145 @@
+/**
+ * Session messaging methods: enqueue, persistUserMessage,
+ * redirectToSecurePrompt, and queue/confirmation helpers.
+ *
+ * Extracted from Session to keep the class focused on coordination.
+ */
+
+import { v4 as uuid } from 'uuid';
+import type { Message } from '../providers/types.js';
+import type { ServerMessage, UserMessageAttachment } from './ipc-protocol.js';
+import { createUserMessage } from '../agent/message-types.js';
+import * as conversationStore from '../memory/conversation-store.js';
+import type { SecretPrompter } from '../permissions/secret-prompter.js';
+import type { MessageQueue } from './session-queue-manager.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('session-messaging');
+
+// ── Context Interface ────────────────────────────────────────────────
+
+export interface MessagingSessionContext {
+  readonly conversationId: string;
+  messages: Message[];
+  processing: boolean;
+  abortController: AbortController | null;
+  currentRequestId?: string;
+  readonly queue: MessageQueue;
+}
+
+// ── enqueueMessage ───────────────────────────────────────────────────
+
+export function enqueueMessage(
+  ctx: MessagingSessionContext,
+  content: string,
+  attachments: UserMessageAttachment[],
+  onEvent: (msg: ServerMessage) => void,
+  requestId: string,
+  activeSurfaceId?: string,
+  currentPage?: string,
+  metadata?: Record<string, unknown>,
+): { queued: boolean; rejected?: boolean; requestId: string } {
+  if (!ctx.processing) {
+    return { queued: false, requestId };
+  }
+
+  const pushed = ctx.queue.push({ content, attachments, requestId, onEvent, activeSurfaceId, currentPage, metadata });
+  if (!pushed) {
+    return { queued: false, rejected: true, requestId };
+  }
+  return { queued: true, requestId };
+}
+
+// ── persistUserMessage ───────────────────────────────────────────────
+
+export function persistUserMessage(
+  ctx: MessagingSessionContext,
+  content: string,
+  attachments: UserMessageAttachment[],
+  requestId?: string,
+  metadata?: Record<string, unknown>,
+): string {
+  if (ctx.processing) {
+    throw new Error('Session is already processing a message');
+  }
+
+  if (!content.trim() && attachments.length === 0) {
+    throw new Error('Message content or attachments are required');
+  }
+
+  const reqId = requestId ?? uuid();
+  ctx.currentRequestId = reqId;
+  ctx.processing = true;
+  ctx.abortController = new AbortController();
+
+  const userMessage = createUserMessage(content, attachments.map((attachment) => ({
+    id: attachment.id,
+    filename: attachment.filename,
+    mimeType: attachment.mimeType,
+    data: attachment.data,
+    extractedText: attachment.extractedText,
+  })));
+  ctx.messages.push(userMessage);
+
+  try {
+    const persistedUserMessage = conversationStore.addMessage(
+      ctx.conversationId,
+      'user',
+      JSON.stringify(userMessage.content),
+      metadata,
+    );
+
+    if (!persistedUserMessage.id) {
+      throw new Error('Failed to persist user message');
+    }
+
+    return persistedUserMessage.id;
+  } catch (err) {
+    ctx.messages.pop();
+    ctx.processing = false;
+    ctx.abortController = null;
+    ctx.currentRequestId = undefined;
+    throw err;
+  }
+}
+
+// ── redirectToSecurePrompt ───────────────────────────────────────────
+
+export function redirectToSecurePrompt(
+  conversationId: string,
+  secretPrompter: SecretPrompter,
+  detectedTypes: string[],
+  onComplete?: () => void,
+): void {
+  const service = 'detected';
+  const field = detectedTypes.join(',');
+  secretPrompter.prompt(
+    service, field,
+    'Secure Credential Entry',
+    'Your message contained a secret. Please enter it here instead — it will be stored securely and never sent to the AI.',
+    undefined, conversationId,
+  ).then(async (result) => {
+    if (!result.value) return;
+
+    const { setSecureKey } = await import('../security/secure-keys.js');
+    const { upsertCredentialMetadata } = await import('../tools/credentials/metadata-store.js');
+
+    if (result.delivery === 'transient_send') {
+      const { credentialBroker } = await import('../tools/credentials/broker.js');
+      credentialBroker.injectTransient(service, field, result.value);
+      try { upsertCredentialMetadata(service, field, {}); } catch (e) { log.debug({ err: e, service, field }, 'Non-critical credential metadata upsert failed'); }
+      log.info({ service, field, delivery: 'transient_send' }, 'Ingress redirect: transient credential injected');
+    } else {
+      const key = `credential:${service}:${field}`;
+      const stored = setSecureKey(key, result.value);
+      if (stored) {
+        try { upsertCredentialMetadata(service, field, {}); } catch (e) { log.debug({ err: e, service, field }, 'Non-critical credential metadata upsert failed'); }
+        log.info({ service, field }, 'Ingress redirect: credential stored');
+      } else {
+        log.warn({ service, field }, 'Ingress redirect: secure storage write failed');
+      }
+    }
+  }).catch(() => { /* prompt timeout or cancel is fine */ }).finally(() => {
+    onComplete?.();
+  });
+}

package/src/daemon/session-notifiers.ts

@@ -0,0 +1,164 @@
+/**
+ * Watch and call notifier registration/unregistration, extracted from
+ * the Session constructor and dispose/abort methods.
+ *
+ * Notifier callbacks read from the provided context object at invocation
+ * time (not registration time), so they always see the latest sendToClient
+ * and messages references even after updateClient().
+ */
+
+import type { Message } from '../providers/types.js';
+import type { ServerMessage } from './ipc-protocol.js';
+import { createAssistantMessage } from '../agent/message-types.js';
+import * as conversationStore from '../memory/conversation-store.js';
+import {
+  registerWatchStartNotifier,
+  unregisterWatchStartNotifier,
+  registerWatchCommentaryNotifier,
+  unregisterWatchCommentaryNotifier,
+  registerWatchCompletionNotifier,
+  unregisterWatchCompletionNotifier,
+  pruneWatchSessions,
+} from '../tools/watch/watch-state.js';
+import type { WatchSession } from '../tools/watch/watch-state.js';
+import { lastCommentaryBySession, lastSummaryBySession } from './watch-handler.js';
+import {
+  registerCallQuestionNotifier,
+  unregisterCallQuestionNotifier,
+  registerCallCompletionNotifier,
+  unregisterCallCompletionNotifier,
+} from '../calls/call-state.js';
+import { getCallSession, getCallEvents } from '../calls/call-store.js';
+
+/**
+ * Subset of Session state that notifier callbacks need to read at
+ * invocation time. Properties are read lazily from this reference.
+ */
+export interface NotifierSessionContext {
+  sendToClient: (msg: ServerMessage) => void;
+  messages: Message[];
+}
+
+/**
+ * Register watch and call notifiers for a session. Call once during
+ * construction; the notifier callbacks close over `ctx` so they see
+ * live sendToClient/messages values.
+ */
+export function registerSessionNotifiers(
+  conversationId: string,
+  ctx: NotifierSessionContext,
+): void {
+  registerWatchStartNotifier(conversationId, (session: WatchSession) => {
+    ctx.sendToClient({
+      type: 'watch_started',
+      sessionId: conversationId,
+      watchId: session.watchId,
+      durationSeconds: session.durationSeconds,
+      intervalSeconds: session.intervalSeconds,
+    });
+  });
+
+  registerWatchCommentaryNotifier(conversationId, (_session: WatchSession) => {
+    const commentary = lastCommentaryBySession.get(conversationId);
+    if (commentary) {
+      lastCommentaryBySession.delete(conversationId);
+      ctx.sendToClient({
+        type: 'assistant_text_delta',
+        text: commentary,
+        sessionId: conversationId,
+      });
+      ctx.sendToClient({
+        type: 'message_complete',
+        sessionId: conversationId,
+      });
+    }
+  });
+
+  registerWatchCompletionNotifier(conversationId, (_session: WatchSession) => {
+    const summary = lastSummaryBySession.get(conversationId);
+    if (summary) {
+      lastSummaryBySession.delete(conversationId);
+      ctx.sendToClient({
+        type: 'assistant_text_delta',
+        text: summary,
+        sessionId: conversationId,
+      });
+      ctx.sendToClient({
+        type: 'message_complete',
+        sessionId: conversationId,
+      });
+    }
+  });
+
+  registerCallQuestionNotifier(conversationId, (callSessionId: string, question: string) => {
+    const callSession = getCallSession(callSessionId);
+    const callee = callSession?.toNumber ?? 'the caller';
+    const questionText = `**Live call question** (to ${callee}):\n\n${question}\n\n_Reply in this thread to answer._`;
+
+    conversationStore.addMessage(
+      conversationId,
+      'assistant',
+      JSON.stringify([{ type: 'text', text: questionText }]),
+    );
+
+    ctx.messages.push(createAssistantMessage(questionText));
+
+    ctx.sendToClient({
+      type: 'assistant_text_delta',
+      text: questionText,
+      sessionId: conversationId,
+    });
+    ctx.sendToClient({
+      type: 'message_complete',
+      sessionId: conversationId,
+    });
+  });
+
+  registerCallCompletionNotifier(conversationId, (callSessionId: string) => {
+    const callSession = getCallSession(callSessionId);
+    const events = getCallEvents(callSessionId);
+    const duration = callSession?.endedAt && callSession?.startedAt
+      ? Math.round((callSession.endedAt - callSession.startedAt) / 1000)
+      : null;
+    const durationStr = duration !== null ? ` (${duration}s)` : '';
+    const summaryText = `**Call completed**${durationStr}. ${events.length} event(s) recorded.`;
+
+    conversationStore.addMessage(
+      conversationId,
+      'assistant',
+      JSON.stringify([{ type: 'text', text: summaryText }]),
+    );
+
+    ctx.messages.push(createAssistantMessage(summaryText));
+
+    ctx.sendToClient({
+      type: 'assistant_text_delta',
+      text: summaryText,
+      sessionId: conversationId,
+    });
+    ctx.sendToClient({
+      type: 'message_complete',
+      sessionId: conversationId,
+    });
+  });
+}
+
+/**
+ * Unregister watch notifiers and prune watch sessions. Called during
+ * abort when the session is actively processing.
+ */
+export function unregisterWatchNotifiers(conversationId: string): void {
+  unregisterWatchStartNotifier(conversationId);
+  unregisterWatchCommentaryNotifier(conversationId);
+  unregisterWatchCompletionNotifier(conversationId);
+  pruneWatchSessions(conversationId);
+}
+
+/**
+ * Unregister call notifiers. Called during dispose regardless of
+ * processing state (notifiers are registered in the constructor).
+ */
+export function unregisterCallNotifiers(conversationId: string): void {
+  unregisterCallQuestionNotifier(conversationId);
+  unregisterCallCompletionNotifier(conversationId);
+}

package/src/daemon/session-process.ts

@@ -55,7 +55,7 @@ export interface ProcessSessionContext {
   currentPage?: string;
   /** Request-scoped skill IDs preactivated via slash resolution. */
   preactivatedSkillIds?: string[];
-  persistUserMessage(content: string, attachments: UserMessageAttachment[], requestId?: string): string;
+  persistUserMessage(content: string, attachments: UserMessageAttachment[], requestId?: string, metadata?: Record<string, unknown>): string;
   runAgentLoop(
     content: string,
     userMessageId: string,
@@ -155,7 +155,7 @@ export function drainQueue(session: ProcessSessionContext, reason: QueueDrainRea
   // resolves early (no runAgentLoop call), so we must continue draining.
   let userMessageId: string;
   try {
-    userMessageId = session.persistUserMessage(resolvedContent, next.attachments, next.requestId);
+    userMessageId = session.persistUserMessage(resolvedContent, next.attachments, next.requestId, next.metadata);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log.error({ err, conversationId: session.conversationId, requestId: next.requestId }, 'Failed to persist queued message');

package/src/daemon/session-queue-manager.ts

@@ -14,6 +14,7 @@ export interface QueuedMessage {
   onEvent: (msg: ServerMessage) => void;
   activeSurfaceId?: string;
   currentPage?: string;
+  metadata?: Record<string, unknown>;
 }
 
 export const MAX_QUEUE_DEPTH = 10;

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

@@ -312,6 +312,44 @@ export function stripWorkspaceTopLevelContext(messages: Message[]): Message[] {
   }).filter((message): message is NonNullable<typeof message> => message !== null);
 }
 
+/**
+ * Prepend temporal context to a user message so the model has
+ * authoritative date/time grounding each turn.
+ */
+export function injectTemporalContext(message: Message, temporalContext: string): Message {
+  return {
+    ...message,
+    content: [
+      { type: 'text', text: temporalContext },
+      ...message.content,
+    ],
+  };
+}
+
+/**
+ * Strip `<temporal_context>` blocks injected by `injectTemporalContext`.
+ * Called after the agent run to prevent temporal context from persisting
+ * in session history.
+ *
+ * Uses a specific prefix (`<temporal_context>\nToday:`) so that
+ * user-authored text that happens to start with `<temporal_context>`
+ * is preserved.
+ */
+const TEMPORAL_INJECTED_PREFIX = '<temporal_context>\nToday:';
+
+export function stripTemporalContext(messages: Message[]): Message[] {
+  return messages.map((message) => {
+    if (message.role !== 'user') return message;
+    const nextContent = message.content.filter((block) => {
+      if (block.type !== 'text') return true;
+      return !block.text.startsWith(TEMPORAL_INJECTED_PREFIX);
+    });
+    if (nextContent.length === message.content.length) return message;
+    if (nextContent.length === 0) return null;
+    return { ...message, content: nextContent };
+  }).filter((message): message is NonNullable<typeof message> => message !== null);
+}
+
 /**
  * Strip `<active_workspace>` (and legacy `<active_dynamic_page>`) blocks
  * injected by `injectActiveSurfaceContext`.  Called after the agent run to
@@ -344,6 +382,7 @@ export function applyRuntimeInjections(
     activeSurface?: ActiveSurfaceContext | null;
     workspaceTopLevelContext?: string | null;
     channelCapabilities?: ChannelCapabilities | null;
+    temporalContext?: string | null;
   },
 ): Message[] {
   let result = runMessages;
@@ -378,6 +417,19 @@ export function applyRuntimeInjections(
     }
   }
 
+  // Temporal context is injected before workspace top-level so it
+  // appears after workspace context in the final message content
+  // (both are prepended, so later injections appear first).
+  if (options.temporalContext) {
+    const userTail = result[result.length - 1];
+    if (userTail && userTail.role === 'user') {
+      result = [
+        ...result.slice(0, -1),
+        injectTemporalContext(userTail, options.temporalContext),
+      ];
+    }
+  }
+
   // Workspace top-level context is injected last so it appears first
   // (prepended) in the user message content, keeping cache breakpoints
   // anchored to the trailing blocks.

package/src/daemon/session-skill-tools.ts

@@ -10,6 +10,7 @@
 
 import type { Message, ToolDefinition } from '../providers/types.js';
 import type { SkillSummary, SkillToolManifest } from '../config/skills.js';
+import type { ActiveSkillEntry } from '../skills/active-skill-tools.js';
 import { loadSkillCatalog } from '../config/skills.js';
 import { deriveActiveSkills } from '../skills/active-skill-tools.js';
 
@@ -38,6 +39,32 @@ export interface SkillToolProjection {
   allowedToolNames: Set<string>;
 }
 
+/**
+ * Session-scoped cache for skill projection. Avoids re-scanning the entire
+ * conversation history and re-reading the filesystem on every agent turn.
+ *
+ * Each session should own its own cache instance to prevent cross-session
+ * state bleed.
+ */
+export interface SkillProjectionCache {
+  /** Cached deriveActiveSkills result. */
+  derived?: {
+    /** Number of messages in history when this cache was last computed. */
+    messageCount: number;
+    /** Reference to the first message when cache was computed. Compaction
+     *  replaces the first message with a new summary object, so a reference
+     *  mismatch signals that history was rewritten even if the count matches. */
+    firstMessage: Message | undefined;
+    /** IDs already seen — used for deduplication during incremental scans. */
+    seenIds: Set<string>;
+    /** The accumulated active skill entries. */
+    entries: ActiveSkillEntry[];
+  };
+  /** Cached skill catalog. Invalidated when the session is marked stale
+   *  (e.g. skill directories changed on disk while a run is in progress). */
+  catalog?: SkillSummary[];
+}
+
 export interface ProjectSkillToolsOptions {
   /** Skill IDs that should be treated as active regardless of history markers. */
   preactivatedSkillIds?: string[];
@@ -49,6 +76,12 @@ export interface ProjectSkillToolsOptions {
    * unregistered and re-registered with the updated definitions.
    */
   previouslyActiveSkillIds?: Map<string, string>;
+  /**
+   * Session-scoped projection cache. When provided, projectSkillTools will
+   * avoid redundant deriveActiveSkills scans and loadSkillCatalog filesystem
+   * reads across agent turns.
+   */
+  cache?: SkillProjectionCache;
 }
 
 // ---------------------------------------------------------------------------
@@ -73,6 +106,82 @@ function loadManifestForSkill(skill: SkillSummary): SkillToolManifest | null {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Cache helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Return active skill entries, using the projection cache when available.
+ *
+ * History is append-only within a session (messages are only added, never
+ * mutated in place). If history.length hasn't changed since the last scan,
+ * the cached result is returned immediately. If new messages were appended,
+ * only the delta is scanned and merged. If history shrank (e.g. compression
+ * replaced earlier messages), the cache is invalidated and a full rescan
+ * is performed.
+ */
+function getCachedActiveSkills(
+  history: Message[],
+  cache?: SkillProjectionCache,
+): ActiveSkillEntry[] {
+  if (!cache) return deriveActiveSkills(history);
+
+  const cached = cache.derived;
+
+  // Fast path: history unchanged since last scan. Both the count and the
+  // first message reference must match — compaction can rewrite history
+  // without changing the total count.
+  if (cached && cached.messageCount === history.length && cached.firstMessage === history[0]) {
+    return cached.entries;
+  }
+
+  // History grew (and first message is unchanged) — scan only the new messages.
+  if (cached && cached.messageCount < history.length && cached.firstMessage === history[0]) {
+    const delta = history.slice(cached.messageCount);
+    const newEntries = deriveActiveSkills(delta);
+
+    // Merge: add any entries not already seen.
+    let changed = false;
+    for (const entry of newEntries) {
+      if (!cached.seenIds.has(entry.id)) {
+        cached.seenIds.add(entry.id);
+        cached.entries.push(entry);
+        changed = true;
+      }
+    }
+
+    cached.messageCount = history.length;
+    if (changed) {
+      log.debug(
+        { newEntries: newEntries.length, total: cached.entries.length },
+        'Incremental skill derivation found new entries',
+      );
+    }
+    return cached.entries;
+  }
+
+  // History shrank, compaction rewrote it, or no cache yet — full rescan.
+  const entries = deriveActiveSkills(history);
+  const seenIds = new Set(entries.map((e) => e.id));
+  cache.derived = { messageCount: history.length, firstMessage: history[0], seenIds, entries };
+  return entries;
+}
+
+/**
+ * Return the skill catalog, caching it across agent turns.
+ *
+ * The cache is invalidated when the session is marked stale (e.g. skill
+ * directories changed on disk while the session is still processing).
+ */
+function getCachedCatalog(cache?: SkillProjectionCache): SkillSummary[] {
+  if (!cache) return loadSkillCatalog();
+
+  if (!cache.catalog) {
+    cache.catalog = loadSkillCatalog();
+  }
+  return cache.catalog;
+}
+
 // ---------------------------------------------------------------------------
 // Main export
 // ---------------------------------------------------------------------------
@@ -90,7 +199,7 @@ export function projectSkillTools(
   history: Message[],
   options?: ProjectSkillToolsOptions,
 ): SkillToolProjection {
-  const contextEntries = deriveActiveSkills(history);
+  const contextEntries = getCachedActiveSkills(history, options?.cache);
   const preactivated = options?.preactivatedSkillIds ?? [];
   const prevActive = options?.previouslyActiveSkillIds ?? new Map<string, string>();
 
@@ -128,8 +237,8 @@ export function projectSkillTools(
     return { toolDefinitions: [], allowedToolNames: new Set() };
   }
 
-  // Load the catalog once and index by ID for efficient lookup
-  const catalog = loadSkillCatalog();
+  // Load the catalog (cached for session lifetime) and index by ID
+  const catalog = getCachedCatalog(options?.cache);
   const catalogById = new Map<string, SkillSummary>();
   for (const skill of catalog) {
     catalogById.set(skill.id, skill);
@@ -138,6 +247,9 @@ export function projectSkillTools(
   const allToolDefinitions: ToolDefinition[] = [];
   const allToolNames = new Set<string>();
   const successfulEntries = new Map<string, string>();
+  // Track skills already unregistered in the version-change branch so the
+  // transiently-failed cleanup loop doesn't double-decrement their refcount.
+  const alreadyUnregistered = new Set<string>();
 
   for (const skillId of activeIds) {
     const skill = catalogById.get(skillId);
@@ -178,7 +290,14 @@ export function projectSkillTools(
         // Hash changed — unregister stale tools, then re-register with new definitions
         log.info({ skillId, prevHash, currentHash }, 'Skill version changed, re-registering tools');
         unregisterSkillTools(skillId);
-        registerSkillTools(tools);
+        alreadyUnregistered.add(skillId);
+        try {
+          registerSkillTools(tools);
+        } catch (err) {
+          log.error({ err, skillId }, 'Failed to re-register skill tools after version change');
+          // Don't add to successfulEntries — will be cleaned up as transiently-failed
+          continue;
+        }
       } else {
         // Hash unchanged — check if the bundled status drifted (e.g. a
         // managed skill override was added/removed with identical content).
@@ -204,7 +323,7 @@ export function projectSkillTools(
   // skill would be re-registered when it recovers next turn, inflating the
   // refcount since the prior registration was never decremented.
   for (const id of prevActive.keys()) {
-    if (activeIds.has(id) && !successfulEntries.has(id)) {
+    if (activeIds.has(id) && !successfulEntries.has(id) && !alreadyUnregistered.has(id)) {
       log.info({ skillId: id }, 'Unregistering tools for transiently-failed skill');
       unregisterSkillTools(id);
     }

package/src/daemon/session-slash.ts

@@ -51,6 +51,9 @@ const PROVIDER_MODEL_SHORTCUTS: Record<string, { provider: string; model: string
 
   // Fireworks
   'fireworks': { provider: 'fireworks', model: 'accounts/fireworks/models/kimi-k2p5', displayName: 'Kimi K2.5' },
+
+  // OpenRouter
+  'openrouter': { provider: 'openrouter', model: 'x-ai/grok-4', displayName: 'Grok 4 (OpenRouter)' },
 };
 
 /** Reverse lookup: model ID → provider, derived from PROVIDER_MODEL_SHORTCUTS. */