vellum 0.0.16 → 0.2.0

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

@@ -0,0 +1,395 @@
+/**
+ * Runtime message-injection helpers extracted from Session.
+ *
+ * These functions modify the user-message tail of the conversation
+ * before it is sent to the provider.  They are pure (no side effects).
+ */
+
+import type { Message } from '../providers/types.js';
+import { listAppFiles, getAppsDir } from '../memory/app-store.js';
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Describes the capabilities of the channel through which the user is
+ * interacting.  Used to gate UI-specific references and permission asks.
+ */
+export interface ChannelCapabilities {
+  /** The raw channel identifier (e.g. "dashboard", "telegram", "http-api"). */
+  channel: string;
+  /** Whether this channel can render the dashboard UI (apps, dynamic pages). */
+  dashboardCapable: boolean;
+  /** Whether the channel supports dynamic UI surfaces (ui_show / ui_update). */
+  supportsDynamicUi: boolean;
+  /** Whether the channel supports voice/microphone input. */
+  supportsVoiceInput: boolean;
+}
+
+/** Derive channel capabilities from a raw source channel identifier. */
+export function resolveChannelCapabilities(sourceChannel?: string | null): ChannelCapabilities {
+  const channel = sourceChannel ?? 'dashboard';
+  const isDashboard = channel === 'dashboard';
+  return {
+    channel,
+    dashboardCapable: isDashboard,
+    supportsDynamicUi: isDashboard,
+    supportsVoiceInput: isDashboard,
+  };
+}
+
+/** Context about the active workspace surface, passed to applyRuntimeInjections. */
+export interface ActiveSurfaceContext {
+  surfaceId: string;
+  html: string;
+  /** When set, the surface is backed by a persisted app. */
+  appId?: string;
+  appName?: string;
+  appSchemaJson?: string;
+  /** Additional pages keyed by filename (e.g. "settings.html" → HTML content). */
+  appPages?: Record<string, string>;
+  /** The page currently displayed in the WebView (e.g. "settings.html"). */
+  currentPage?: string;
+  /** Pre-fetched list of files in the app directory. */
+  appFiles?: string[];
+}
+
+/**
+ * Append a memory-conflict clarification instruction to the last user message.
+ */
+export function injectClarificationRequestIntoUserMessage(message: Message, question: string): Message {
+  const instruction = [
+    '[Memory clarification request]',
+    `Ask this once in your response: ${question}`,
+    'After asking, continue helping with the current request.',
+  ].join('\n');
+  return {
+    ...message,
+    content: [
+      ...message.content,
+      { type: 'text', text: `\n\n${instruction}` },
+    ],
+  };
+}
+
+const MAX_CONTEXT_LENGTH = 100_000;
+
+function truncateHtml(html: string, budget: number): string {
+  if (html.length <= budget) return html;
+  return html.slice(0, budget) + `\n<!-- truncated: original is ${html.length} characters -->`;
+}
+
+/**
+ * Prepend workspace context so the model can refine UI surfaces.
+ * Adapts the injected rules based on whether the surface is app-backed.
+ */
+export function injectActiveSurfaceContext(message: Message, ctx: ActiveSurfaceContext): Message {
+  const lines: string[] = ['<active_workspace>'];
+
+  if (ctx.appId) {
+    // ── App-backed surface ──
+    lines.push(
+      `The user is viewing app "${ctx.appName ?? 'Untitled'}" (app_id: "${ctx.appId}") in workspace mode.`,
+      '',
+      'PREREQUISITE: If `app_*` tools (e.g. `app_file_edit`, `app_file_write`) are not yet available, call `skill_load` with `id: "app-builder"` first to load them.',
+      '',
+      'RULES FOR WORKSPACE MODIFICATION:',
+      `1. Use \`app_file_edit\` with app_id "${ctx.appId}" for surgical changes.`,
+      '   Provide old_string (exact match) and new_string (replacement).',
+      '   Include a short `status` message describing what you\'re doing (e.g. "adding dark mode styles").',
+      '2. Use `app_file_write` to create new files or fully rewrite files. Include `status`.',
+      '3. Use `app_file_read` to read any file with line numbers before editing.',
+      '4. Use `app_file_list` to see all files in the app.',
+      '5. The surface refreshes automatically after file edits — do NOT call app_update, ui_show, or ui_update.',
+      '6. NEVER respond with only text — the user expects a visual update.',
+      '7. Make ONLY the changes the user requested. Preserve existing content/styling.',
+      '8. Keep your text response to 1 brief sentence confirming what you changed.',
+    );
+
+    if (ctx.html.includes('data-vellum-home-base="v1"')) {
+      lines.push(
+        '9. This is the prebuilt Home Base scaffold. Preserve layout anchors:',
+        '   `home-base-root`, `home-base-onboarding-lane`, and `home-base-starter-lane`.',
+      );
+    }
+
+    // File tree with sizes (capped at 50 files to bound prompt size)
+    const files = ctx.appFiles ?? listAppFiles(ctx.appId);
+    const MAX_FILE_TREE_ENTRIES = 50;
+    const displayFiles = files.slice(0, MAX_FILE_TREE_ENTRIES);
+    lines.push('', 'App files:');
+    for (const filePath of displayFiles) {
+      let sizeLabel: string;
+      try {
+        const bytes = statSync(join(getAppsDir(), ctx.appId, filePath)).size;
+        sizeLabel = bytes < 1000 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`;
+      } catch {
+        sizeLabel = '? KB';
+      }
+      lines.push(`  ${filePath} (${sizeLabel})`);
+    }
+    if (files.length > MAX_FILE_TREE_ENTRIES) {
+      lines.push(`  ... and ${files.length - MAX_FILE_TREE_ENTRIES} more files`);
+    }
+
+    // Schema metadata
+    const schema = ctx.appSchemaJson;
+    const MAX_SCHEMA_LENGTH = 10_000;
+    if (schema && schema !== '"{}"' && schema !== '{}') {
+      const truncatedSchema = schema.length > MAX_SCHEMA_LENGTH
+        ? schema.slice(0, MAX_SCHEMA_LENGTH) + '… (truncated)'
+        : schema;
+      lines.push('', `Data schema: ${truncatedSchema}`);
+    }
+
+    // Determine which file content to show based on the currently viewed page
+    const viewingPage = ctx.currentPage && ctx.currentPage !== 'index.html' ? ctx.currentPage : null;
+    let primaryLabel = 'index.html';
+    let primaryContent = ctx.html;
+    if (viewingPage && ctx.appPages?.[viewingPage]) {
+      primaryLabel = viewingPage;
+      primaryContent = ctx.appPages[viewingPage];
+    }
+
+    // Line-numbered current file content
+    const schemaSize = schema ? Math.min(schema.length, MAX_SCHEMA_LENGTH) : 0;
+    // Reduce budget by 15% to account for line-number prefix overhead (~7 chars/line)
+    let mainBudget = Math.floor((MAX_CONTEXT_LENGTH - schemaSize) * 0.85);
+    const additionalPageBlocks: string[] = [];
+
+    // Build additional page content (all pages except the primary one)
+    const otherPages: Record<string, string> = {};
+    if (viewingPage && primaryLabel !== 'index.html') {
+      otherPages['index.html'] = ctx.html;
+    }
+    if (ctx.appPages) {
+      for (const [filename, content] of Object.entries(ctx.appPages)) {
+        if (filename !== primaryLabel) {
+          otherPages[filename] = content;
+        }
+      }
+    }
+
+    if (Object.keys(otherPages).length > 0) {
+      let additionalSize = 0;
+      for (const [filename, content] of Object.entries(otherPages)) {
+        additionalSize += filename.length + content.length + 30;
+        additionalPageBlocks.push(`--- ${filename} ---`, content);
+      }
+      if (additionalSize + primaryContent.length > MAX_CONTEXT_LENGTH - schemaSize) {
+        additionalPageBlocks.length = 0;
+      } else {
+        mainBudget = Math.floor((MAX_CONTEXT_LENGTH - schemaSize - additionalSize) * 0.85);
+      }
+    }
+
+    // Format file content with line numbers (cat -n style)
+    const truncatedContent = truncateHtml(primaryContent, mainBudget);
+    const numberedLines = truncatedContent.split('\n').map((line, i) => {
+      const num = String(i + 1);
+      return `${num.padStart(6)}\t${line}`;
+    }).join('\n');
+    lines.push('', `--- ${primaryLabel} ---`, numberedLines);
+
+    if (additionalPageBlocks.length > 0) {
+      lines.push('', 'Additional page content:', ...additionalPageBlocks);
+    }
+  } else {
+    // ── Ephemeral surface (created via ui_show, no persisted app) ──
+    lines.push(
+      `The user is viewing a dynamic page (surface_id: "${ctx.surfaceId}") in workspace mode.`,
+      '',
+      'RULES FOR WORKSPACE MODIFICATION:',
+      `1. You MUST call \`ui_update\` with surface_id "${ctx.surfaceId}" and data.html containing`,
+      '   the complete updated HTML.',
+      '   NEVER respond with only text — the user expects a visual update every time they',
+      '   send a message here. Even if the page appears to already show what they want,',
+      '   call ui_update anyway (the user sees a broken experience when no update arrives).',
+      '2. You MAY call other tools first to gather data before calling ui_update.',
+      '3. Do NOT call ui_show — modify the existing page.',
+      '4. Make ONLY the changes the user requested. Preserve all existing content,',
+      '   styling, and functionality unless explicitly asked to change them.',
+      '5. Keep your text response to 1 brief sentence confirming what you changed.',
+      '',
+      'Current HTML:',
+      truncateHtml(ctx.html, MAX_CONTEXT_LENGTH),
+    );
+  }
+
+  lines.push('</active_workspace>');
+
+  const block = lines.join('\n');
+  return {
+    ...message,
+    content: [
+      { type: 'text', text: block },
+      ...message.content,
+    ],
+  };
+}
+
+/**
+ * Prepend channel capability context to the last user message so the
+ * model knows what the current channel can and cannot do.
+ */
+export function injectChannelCapabilityContext(message: Message, caps: ChannelCapabilities): Message {
+  const lines: string[] = ['<channel_capabilities>'];
+  lines.push(`channel: ${caps.channel}`);
+  lines.push(`dashboard_capable: ${caps.dashboardCapable}`);
+  lines.push(`supports_dynamic_ui: ${caps.supportsDynamicUi}`);
+  lines.push(`supports_voice_input: ${caps.supportsVoiceInput}`);
+
+  if (!caps.dashboardCapable) {
+    lines.push('');
+    lines.push('CHANNEL CONSTRAINTS:');
+    lines.push('- Do NOT reference the dashboard UI, settings panels, or visual preference pickers.');
+    lines.push('- Do NOT use ui_show, ui_update, or app_create — this channel cannot render them.');
+    lines.push('- Present information as well-formatted text instead of dynamic UI.');
+    lines.push('- Defer dashboard-specific actions (e.g. accent color selection) by telling the user');
+    lines.push('  they can complete those steps later from the desktop app.');
+  }
+
+  if (!caps.supportsVoiceInput) {
+    lines.push('- Do NOT ask the user to use voice or microphone input.');
+  }
+
+  lines.push('</channel_capabilities>');
+
+  const block = lines.join('\n');
+  return {
+    ...message,
+    content: [
+      { type: 'text', text: block },
+      ...message.content,
+    ],
+  };
+}
+
+/**
+ * Strip `<channel_capabilities>` blocks injected by
+ * `injectChannelCapabilityContext`.
+ */
+export function stripChannelCapabilityContext(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('<channel_capabilities>');
+    });
+    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);
+}
+
+/**
+ * Prepend workspace top-level directory context to a user message.
+ */
+export function injectWorkspaceTopLevelContext(message: Message, contextText: string): Message {
+  return {
+    ...message,
+    content: [
+      { type: 'text', text: contextText },
+      ...message.content,
+    ],
+  };
+}
+
+/**
+ * Strip `<workspace_top_level>` blocks injected by
+ * `injectWorkspaceTopLevelContext`.  Called after the agent run to prevent
+ * workspace context from persisting in session history.
+ */
+export function stripWorkspaceTopLevelContext(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('<workspace_top_level>');
+    });
+    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
+ * prevent the (potentially 100 KB) surface HTML from persisting in session
+ * history.
+ */
+export function stripActiveSurfaceContext(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('<active_workspace>') && !block.text.startsWith('<active_dynamic_page>');
+    });
+    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);
+}
+
+/**
+ * Apply a chain of user-message injections to `runMessages`.
+ *
+ * Each injection is optional — pass `null`/`undefined` to skip it.
+ * Returns the final message array ready for the provider.
+ */
+export function applyRuntimeInjections(
+  runMessages: Message[],
+  options: {
+    softConflictInstruction?: string | null;
+    activeSurface?: ActiveSurfaceContext | null;
+    workspaceTopLevelContext?: string | null;
+    channelCapabilities?: ChannelCapabilities | null;
+  },
+): Message[] {
+  let result = runMessages;
+
+  if (options.softConflictInstruction) {
+    const userTail = result[result.length - 1];
+    if (userTail && userTail.role === 'user') {
+      result = [
+        ...result.slice(0, -1),
+        injectClarificationRequestIntoUserMessage(userTail, options.softConflictInstruction),
+      ];
+    }
+  }
+
+  if (options.activeSurface) {
+    const userTail = result[result.length - 1];
+    if (userTail && userTail.role === 'user') {
+      result = [
+        ...result.slice(0, -1),
+        injectActiveSurfaceContext(userTail, options.activeSurface),
+      ];
+    }
+  }
+
+  if (options.channelCapabilities) {
+    const userTail = result[result.length - 1];
+    if (userTail && userTail.role === 'user') {
+      result = [
+        ...result.slice(0, -1),
+        injectChannelCapabilityContext(userTail, options.channelCapabilities),
+      ];
+    }
+  }
+
+  // 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.
+  if (options.workspaceTopLevelContext) {
+    const userTail = result[result.length - 1];
+    if (userTail && userTail.role === 'user') {
+      result = [
+        ...result.slice(0, -1),
+        injectWorkspaceTopLevelContext(userTail, options.workspaceTopLevelContext),
+      ];
+    }
+  }
+
+  return result;
+}

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

@@ -0,0 +1,237 @@
+/**
+ * Session-time projection of active skill tools.
+ *
+ * On each agent turn the conversation history (and any pre-activated IDs from
+ * config or slash commands) determine which skills are "active".  This module
+ * computes the union, loads tool manifests, registers new skill tools, tears
+ * down tools for skills that are no longer active, and returns the projected
+ * tool definitions so the agent loop can include them in the next request.
+ */
+
+import type { Message, ToolDefinition } from '../providers/types.js';
+import type { SkillSummary, SkillToolManifest } from '../config/skills.js';
+import { loadSkillCatalog } from '../config/skills.js';
+import { deriveActiveSkills } from '../skills/active-skill-tools.js';
+
+import { parseToolManifestFile } from '../skills/tool-manifest.js';
+import { computeSkillVersionHash } from '../skills/version-hash.js';
+import { createSkillToolsFromManifest } from '../tools/skills/skill-tool-factory.js';
+import {
+  getTool,
+  registerSkillTools,
+  unregisterSkillTools,
+} from '../tools/registry.js';
+import { getLogger } from '../util/logger.js';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+const log = getLogger('session-skill-tools');
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface SkillToolProjection {
+  /** Tool definitions to append to the agent's tool list for this turn. */
+  toolDefinitions: ToolDefinition[];
+  /** Tool names that belong to currently active skills. */
+  allowedToolNames: Set<string>;
+}
+
+export interface ProjectSkillToolsOptions {
+  /** Skill IDs that should be treated as active regardless of history markers. */
+  preactivatedSkillIds?: string[];
+  /**
+   * Session-scoped tracking map of previously active skill IDs to their
+   * version hashes. Each session should own its own map to prevent
+   * cross-session state bleed when the daemon serves multiple concurrent
+   * sessions. When a skill's hash changes between turns, its tools are
+   * unregistered and re-registered with the updated definitions.
+   */
+  previouslyActiveSkillIds?: Map<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Load and parse a skill's TOOLS.json manifest, returning null on any failure.
+ */
+function loadManifestForSkill(skill: SkillSummary): SkillToolManifest | null {
+  const manifestPath = join(skill.directoryPath, 'TOOLS.json');
+  if (!existsSync(manifestPath)) {
+    log.debug({ skillId: skill.id, manifestPath }, 'No TOOLS.json found for skill');
+    return null;
+  }
+
+  try {
+    return parseToolManifestFile(manifestPath);
+  } catch (err) {
+    log.warn({ err, skillId: skill.id, manifestPath }, 'Failed to parse TOOLS.json for skill');
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the set of active skill tools for the current session turn.
+ *
+ * 1. Derives active skill IDs from conversation history markers.
+ * 2. Merges with any preactivated IDs (union).
+ * 3. For each newly-active skill, loads its TOOLS.json and registers tools.
+ * 4. For each previously-active skill that is no longer active, unregisters.
+ * 5. Returns projected tool definitions and the set of allowed tool names.
+ */
+export function projectSkillTools(
+  history: Message[],
+  options?: ProjectSkillToolsOptions,
+): SkillToolProjection {
+  const contextEntries = deriveActiveSkills(history);
+  const preactivated = options?.preactivatedSkillIds ?? [];
+  const prevActive = options?.previouslyActiveSkillIds ?? new Map<string, string>();
+
+  // Index marker versions by skill ID so we can use them during registration.
+  // When a marker carries a version, it records the hash that was active at
+  // load time — useful for detecting drift without re-hashing the directory.
+  const markerVersionById = new Map<string, string>();
+  for (const entry of contextEntries) {
+    if (entry.version) {
+      markerVersionById.set(entry.id, entry.version);
+    }
+  }
+
+  // Union of context-derived and preactivated IDs
+  const contextIds = contextEntries.map((e) => e.id);
+  const activeIds = new Set<string>([...contextIds, ...preactivated]);
+
+  // Determine which skills were removed since last projection
+  const removedIds = new Set<string>();
+  for (const id of prevActive.keys()) {
+    if (!activeIds.has(id)) {
+      removedIds.add(id);
+    }
+  }
+
+  // Unregister tools for skills that are no longer active
+  for (const id of removedIds) {
+    log.info({ skillId: id }, 'Unregistering tools for deactivated skill');
+    unregisterSkillTools(id);
+  }
+
+  // Early exit if nothing is active
+  if (activeIds.size === 0) {
+    prevActive.clear();
+    return { toolDefinitions: [], allowedToolNames: new Set() };
+  }
+
+  // Load the catalog once and index by ID for efficient lookup
+  const catalog = loadSkillCatalog();
+  const catalogById = new Map<string, SkillSummary>();
+  for (const skill of catalog) {
+    catalogById.set(skill.id, skill);
+  }
+
+  const allToolDefinitions: ToolDefinition[] = [];
+  const allToolNames = new Set<string>();
+  const successfulEntries = new Map<string, string>();
+
+  for (const skillId of activeIds) {
+    const skill = catalogById.get(skillId);
+    if (!skill) {
+      log.warn({ skillId }, 'Active skill ID not found in catalog');
+      continue;
+    }
+
+    const manifest = loadManifestForSkill(skill);
+    if (!manifest) {
+      continue;
+    }
+
+    // Compute the current version hash for this skill directory
+    let currentHash: string;
+    try {
+      currentHash = computeSkillVersionHash(skill.directoryPath);
+    } catch (err) {
+      log.warn({ err, skillId }, 'Failed to compute skill version hash, treating as changed');
+      currentHash = `unknown-${Date.now()}`;
+    }
+
+    // Create runtime Tool objects
+    const tools = createSkillToolsFromManifest(
+      manifest.tools,
+      skillId,
+      skill.directoryPath,
+      currentHash,
+      skill.bundled,
+    );
+
+    if (tools.length > 0) {
+      const prevHash = prevActive.get(skillId);
+      if (prevHash === undefined) {
+        // Newly active skill — register for the first time
+        registerSkillTools(tools);
+      } else if (prevHash !== currentHash) {
+        // 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);
+      } else {
+        // Hash unchanged — check if the bundled status drifted (e.g. a
+        // managed skill override was added/removed with identical content).
+        // Re-register so the ownerSkillBundled flag stays accurate.
+        const existing = getTool(tools[0].name);
+        if (existing && existing.ownerSkillBundled !== (skill.bundled ?? undefined)) {
+          log.info({ skillId, bundled: skill.bundled }, 'Skill bundled status changed, re-registering tools');
+          unregisterSkillTools(skillId);
+          registerSkillTools(tools);
+        }
+      }
+
+      successfulEntries.set(skillId, currentHash);
+      for (const tool of tools) {
+        allToolDefinitions.push(tool.getDefinition());
+        allToolNames.add(tool.name);
+      }
+    }
+  }
+
+  // Unregister skills that were previously active but failed processing this
+  // turn (catalog miss, manifest failure, empty tools). Without this, the
+  // 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)) {
+      log.info({ skillId: id }, 'Unregistering tools for transiently-failed skill');
+      unregisterSkillTools(id);
+    }
+  }
+
+  // Update the session-scoped tracking map in-place — only include skills
+  // that were successfully processed so failed skills can be retried next turn.
+  prevActive.clear();
+  for (const [id, hash] of successfulEntries) {
+    prevActive.set(id, hash);
+  }
+
+  return {
+    toolDefinitions: allToolDefinitions,
+    allowedToolNames: allToolNames,
+  };
+}
+
+/**
+ * Reset the projection state and unregister all skill tools tracked in the
+ * given map. Used for session teardown and tests.
+ */
+export function resetSkillToolProjection(trackedIds?: Map<string, string>): void {
+  if (trackedIds) {
+    for (const id of trackedIds.keys()) {
+      unregisterSkillTools(id);
+    }
+    trackedIds.clear();
+  }
+}