vellum 0.2.1 → 0.2.2

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. */

package/src/daemon/session-surfaces.ts

@@ -4,6 +4,7 @@ import type {
   ServerMessage,
   SurfaceType,
   SurfaceData,
+  CardSurfaceData,
   DynamicPageSurfaceData,
   FileUploadSurfaceData,
   UiSurfaceShow,
@@ -20,6 +21,74 @@ import {
 const log = getLogger('session-surfaces');
 
 const MAX_UNDO_DEPTH = 10;
+const TASK_PROGRESS_TEMPLATE_FIELDS = ['title', 'status', 'steps'] as const;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function normalizeCardShowData(input: Record<string, unknown>, rawData: Record<string, unknown>): CardSurfaceData {
+  const normalized: Record<string, unknown> = { ...rawData };
+
+  // Older prompt examples sent template/templateData at the top level.
+  if (typeof normalized.template !== 'string' && typeof input.template === 'string') {
+    normalized.template = input.template;
+  }
+  if (!isPlainObject(normalized.templateData) && isPlainObject(input.templateData)) {
+    normalized.templateData = input.templateData;
+  }
+
+  // task_progress cards need a title for Swift parsing; fall back when missing.
+  if (normalized.template === 'task_progress' && typeof normalized.title !== 'string') {
+    if (typeof input.title === 'string' && input.title.trim().length > 0) {
+      normalized.title = input.title;
+    } else if (isPlainObject(normalized.templateData) && typeof normalized.templateData.title === 'string') {
+      normalized.title = normalized.templateData.title;
+    } else {
+      normalized.title = 'Task Progress';
+    }
+  }
+
+  if (normalized.template === 'task_progress' && typeof normalized.body !== 'string') {
+    normalized.body = '';
+  }
+
+  return normalized as unknown as CardSurfaceData;
+}
+
+function normalizeTaskProgressCardPatch(existingCard: CardSurfaceData, patch: Record<string, unknown>): Record<string, unknown> {
+  if (existingCard.template !== 'task_progress') {
+    return patch;
+  }
+
+  const normalizedPatch: Record<string, unknown> = { ...patch };
+  const mergedTemplateData: Record<string, unknown> = isPlainObject(existingCard.templateData)
+    ? { ...existingCard.templateData }
+    : {};
+
+  let updatedTemplateData = false;
+
+  if (isPlainObject(normalizedPatch.templateData)) {
+    Object.assign(mergedTemplateData, normalizedPatch.templateData);
+    updatedTemplateData = true;
+  }
+
+  // Accept top-level task_progress fields from older prompt examples and
+  // move them into templateData where the Swift client expects them.
+  for (const key of TASK_PROGRESS_TEMPLATE_FIELDS) {
+    if (key in normalizedPatch) {
+      mergedTemplateData[key] = normalizedPatch[key];
+      delete normalizedPatch[key];
+      updatedTemplateData = true;
+    }
+  }
+
+  if (updatedTemplateData) {
+    normalizedPatch.templateData = mergedTemplateData;
+  }
+
+  return normalizedPatch;
+}
 
 /**
  * Subset of Session state that surface helpers need access to.
@@ -447,7 +516,10 @@ export async function surfaceProxyResolver(
     const surfaceId = uuid();
     const surfaceType = input.surface_type as SurfaceType;
     const title = typeof input.title === 'string' ? input.title : undefined;
-    const data = input.data as SurfaceData;
+    const rawData = isPlainObject(input.data) ? input.data : {};
+    const data = (surfaceType === 'card'
+      ? normalizeCardShowData(input, rawData)
+      : rawData) as SurfaceData;
     const actions = input.actions as Array<{ id: string; label: string; style?: string }> | undefined;
     // Interactive surfaces default to awaiting user action.
     const hasActions = Array.isArray(actions) && actions.length > 0;
@@ -502,12 +574,15 @@ export async function surfaceProxyResolver(
 
   if (toolName === 'ui_update') {
     const surfaceId = input.surface_id as string;
-    const patch = input.data as Record<string, unknown>;
+    let patch = (isPlainObject(input.data) ? input.data : {}) as Record<string, unknown>;
 
     // Merge the partial patch into the stored full surface data
     const stored = ctx.surfaceState.get(surfaceId);
     let mergedData: SurfaceData;
     if (stored) {
+      if (stored.surfaceType === 'card') {
+        patch = normalizeTaskProgressCardPatch(stored.data as CardSurfaceData, patch);
+      }
       // Push current HTML to undo stack for dynamic pages
       if (stored.surfaceType === 'dynamic_page') {
         const currentHtml = (stored.data as DynamicPageSurfaceData).html;