@vellumai/assistant 0.3.0

package/src/autonomy/autonomy-resolver.ts

@@ -0,0 +1,60 @@
+/**
+ * Autonomy resolver — determines the effective autonomy tier for an
+ * inbound message based on its triage result, channel, and contact.
+ *
+ * Resolution order (first match wins):
+ *   1. Matched playbook with an explicit autonomy level
+ *   2. Contact-specific override
+ *   3. Category override for the triage result's category
+ *   4. Channel default
+ *   5. Global default tier (falls back to 'notify')
+ */
+
+import type { TriageResult } from '../messaging/types.js';
+import type { AutonomyTier } from './types.js';
+import { AUTONOMY_TIERS } from './types.js';
+import { getAutonomyConfig } from './autonomy-store.js';
+
+/**
+ * Resolve the autonomy tier for a triaged message.
+ *
+ * @param triageResult - Output from the triage engine
+ * @param channel      - The channel the message arrived on (e.g. 'email', 'slack')
+ * @param contactId    - Optional contact ID for contact-specific overrides
+ */
+export function resolveAutonomyTier(
+  triageResult: TriageResult,
+  channel: string,
+  contactId?: string,
+): AutonomyTier {
+  // 1. Playbook-specified autonomy level (first matched playbook wins)
+  for (const playbook of triageResult.matchedPlaybooks) {
+    if (isValidTier(playbook.autonomyLevel)) {
+      return playbook.autonomyLevel as AutonomyTier;
+    }
+  }
+
+  const config = getAutonomyConfig();
+
+  // 2. Contact-specific override
+  if (contactId && Object.hasOwn(config.contactOverrides, contactId)) {
+    return config.contactOverrides[contactId];
+  }
+
+  // 3. Category override
+  if (Object.hasOwn(config.categoryOverrides, triageResult.category)) {
+    return config.categoryOverrides[triageResult.category];
+  }
+
+  // 4. Channel default
+  if (Object.hasOwn(config.channelDefaults, channel)) {
+    return config.channelDefaults[channel];
+  }
+
+  // 5. Global default
+  return config.defaultTier;
+}
+
+function isValidTier(value: unknown): value is AutonomyTier {
+  return typeof value === 'string' && AUTONOMY_TIERS.includes(value as AutonomyTier);
+}

package/src/autonomy/autonomy-store.ts

@@ -0,0 +1,122 @@
+/**
+ * Autonomy config persistence — reads/writes autonomy policy from a
+ * dedicated JSON file in the workspace directory.
+ *
+ * The autonomy config lives at ~/.vellum/workspace/autonomy.json, separate
+ * from the main config.json. This is policy configuration (not learned
+ * preferences), so it belongs on disk rather than in the SQLite database.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { getWorkspaceDir } from '../util/platform.js';
+import { getLogger } from '../util/logger.js';
+import type { AutonomyConfig, AutonomyTier } from './types.js';
+import { DEFAULT_AUTONOMY_CONFIG, AUTONOMY_TIERS } from './types.js';
+
+const log = getLogger('autonomy-store');
+
+function getAutonomyConfigPath(): string {
+  return join(getWorkspaceDir(), 'autonomy.json');
+}
+
+/**
+ * Load the current autonomy configuration from disk.
+ * Returns defaults if the file doesn't exist or is malformed.
+ */
+export function getAutonomyConfig(): AutonomyConfig {
+  const configPath = getAutonomyConfigPath();
+  if (!existsSync(configPath)) {
+    return structuredClone(DEFAULT_AUTONOMY_CONFIG);
+  }
+
+  try {
+    const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+    return validateAutonomyConfig(raw);
+  } catch (err) {
+    log.warn({ err }, 'Failed to parse autonomy config; using defaults');
+    return structuredClone(DEFAULT_AUTONOMY_CONFIG);
+  }
+}
+
+/**
+ * Merge partial updates into the existing autonomy configuration and persist.
+ * Only the provided fields are updated; omitted fields keep their current values.
+ */
+export function setAutonomyConfig(updates: Partial<AutonomyConfig>): AutonomyConfig {
+  const current = getAutonomyConfig();
+
+  if (updates.defaultTier !== undefined) {
+    current.defaultTier = updates.defaultTier;
+  }
+  if (updates.channelDefaults !== undefined) {
+    current.channelDefaults = { ...current.channelDefaults, ...updates.channelDefaults };
+  }
+  if (updates.categoryOverrides !== undefined) {
+    current.categoryOverrides = { ...current.categoryOverrides, ...updates.categoryOverrides };
+  }
+  if (updates.contactOverrides !== undefined) {
+    current.contactOverrides = { ...current.contactOverrides, ...updates.contactOverrides };
+  }
+
+  persistConfig(current);
+  return current;
+}
+
+/**
+ * Get the autonomy tier configured for a specific channel.
+ * Returns undefined if no channel-specific default is set.
+ */
+export function getChannelDefault(channel: string): AutonomyTier | undefined {
+  const config = getAutonomyConfig();
+  return config.channelDefaults[channel];
+}
+
+/**
+ * Set the autonomy tier for a specific channel.
+ */
+export function setChannelDefault(channel: string, tier: AutonomyTier): void {
+  const config = getAutonomyConfig();
+  config.channelDefaults[channel] = tier;
+  persistConfig(config);
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function persistConfig(config: AutonomyConfig): void {
+  const configPath = getAutonomyConfigPath();
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+}
+
+function isValidTier(value: unknown): value is AutonomyTier {
+  return typeof value === 'string' && AUTONOMY_TIERS.includes(value as AutonomyTier);
+}
+
+function validateTierRecord(raw: unknown): Record<string, AutonomyTier> {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {};
+  const result: Record<string, AutonomyTier> = {};
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (isValidTier(value)) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+function validateAutonomyConfig(raw: unknown): AutonomyConfig {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return structuredClone(DEFAULT_AUTONOMY_CONFIG);
+  }
+
+  const obj = raw as Record<string, unknown>;
+
+  return {
+    defaultTier: isValidTier(obj.defaultTier) ? obj.defaultTier : DEFAULT_AUTONOMY_CONFIG.defaultTier,
+    channelDefaults: validateTierRecord(obj.channelDefaults),
+    categoryOverrides: validateTierRecord(obj.categoryOverrides),
+    contactOverrides: validateTierRecord(obj.contactOverrides),
+  };
+}

package/src/autonomy/disposition-mapper.ts

@@ -0,0 +1,31 @@
+/**
+ * Disposition mapper — bridges autonomy tiers to watcher event dispositions.
+ *
+ * The watcher engine uses three dispositions for event handling:
+ *   - `silent`   — act without notifying the user
+ *   - `notify`   — alert the user (with optional draft attached)
+ *   - `escalate` — alert the user and take no autonomous action
+ *
+ * This module maps autonomy tiers to those dispositions:
+ *   - `auto`   → `silent`   (act without notifying)
+ *   - `draft`  → `notify`   (prepare draft, alert user for approval)
+ *   - `notify` → `escalate` (alert user, take no action)
+ */
+
+import type { AutonomyTier } from './types.js';
+
+/** Watcher event disposition strings used by the watcher engine. */
+export type WatcherDisposition = 'silent' | 'notify' | 'escalate';
+
+const TIER_TO_DISPOSITION: Record<AutonomyTier, WatcherDisposition> = {
+  auto: 'silent',
+  draft: 'notify',
+  notify: 'escalate',
+};
+
+/**
+ * Map an autonomy tier to the corresponding watcher disposition.
+ */
+export function mapTierToDisposition(tier: AutonomyTier): WatcherDisposition {
+  return TIER_TO_DISPOSITION[tier];
+}

package/src/autonomy/index.ts

@@ -0,0 +1,11 @@
+export type { AutonomyTier, AutonomyConfig } from './types.js';
+export { AUTONOMY_TIERS, DEFAULT_AUTONOMY_CONFIG } from './types.js';
+export {
+  getAutonomyConfig,
+  setAutonomyConfig,
+  getChannelDefault,
+  setChannelDefault,
+} from './autonomy-store.js';
+export { resolveAutonomyTier } from './autonomy-resolver.js';
+export type { WatcherDisposition } from './disposition-mapper.js';
+export { mapTierToDisposition } from './disposition-mapper.js';

package/src/autonomy/types.ts

@@ -0,0 +1,39 @@
+/**
+ * Autonomy tier types — govern what runs unsupervised per channel/category/contact.
+ *
+ * Three tiers:
+ * - `auto`   — act silently, no human in the loop
+ * - `draft`  — prepare a draft for human approval before sending
+ * - `notify` — alert the user but take no action (most conservative)
+ */
+
+export type AutonomyTier = 'auto' | 'draft' | 'notify';
+
+export const AUTONOMY_TIERS: readonly AutonomyTier[] = ['auto', 'draft', 'notify'] as const;
+
+/**
+ * Policy configuration for autonomy tiers. This is persisted as JSON config,
+ * not in the SQLite database — it represents explicit policy decisions, not
+ * learned preferences.
+ */
+export interface AutonomyConfig {
+  /** Global fallback tier when no more-specific rule matches. Defaults to 'notify'. */
+  defaultTier: AutonomyTier;
+
+  /** Per-channel defaults (e.g., { email: 'draft', slack: 'auto' }). */
+  channelDefaults: Record<string, AutonomyTier>;
+
+  /** Per-category overrides keyed by triage category (e.g., { newsletter: 'auto' }). */
+  categoryOverrides: Record<string, AutonomyTier>;
+
+  /** Per-contact overrides keyed by contact ID. */
+  contactOverrides: Record<string, AutonomyTier>;
+}
+
+/** Sensible defaults — conservative: everything starts as notify-only. */
+export const DEFAULT_AUTONOMY_CONFIG: AutonomyConfig = {
+  defaultTier: 'notify',
+  channelDefaults: {},
+  categoryOverrides: {},
+  contactOverrides: {},
+};

package/src/bundler/app-bundler.ts

@@ -0,0 +1,295 @@
+/**
+ * Core packaging logic for .vellumapp zip archives.
+ *
+ * Reads an app from the app-store, generates a manifest, and produces a
+ * zip archive written to a temp file.
+ */
+
+import { createWriteStream } from 'node:fs';
+import { readFile, writeFile, stat } from 'node:fs/promises';
+import { join, extname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomUUID, createHash } from 'node:crypto';
+import archiver from 'archiver';
+import JSZip from 'jszip';
+import { getApp } from '../memory/app-store.js';
+import type { AppManifest } from './manifest.js';
+import { serializeManifest } from './manifest.js';
+import { signBundle } from './bundle-signer.js';
+import type { SigningCallback } from './bundle-signer.js';
+import { getLogger } from '../util/logger.js';
+import { computeContentId } from '../util/content-id.js';
+
+const bundlerLog = getLogger('app-bundler');
+
+import { APP_VERSION } from '../version.js';
+const PACKAGE_VERSION = APP_VERSION;
+
+const SHORT_HASH_LENGTH = 8;
+const HASH_DISPLAY_LENGTH = 12;
+const MAX_BUNDLE_SIZE_BYTES = 25 * 1024 * 1024; // 25 MB
+const ASSET_FETCH_TIMEOUT_MS = 10_000;
+
+interface FetchedAsset {
+  archivePath: string; // e.g. "assets/a1b2c3d4.png"
+  data: Buffer;
+}
+
+/**
+ * Extract all remote (http/https) URLs from HTML content.
+ * Looks in src=, href= on all elements except <a> tags, and CSS url() references.
+ */
+export function extractRemoteUrls(html: string): string[] {
+  const urls = new Set<string>();
+
+  // Match src="..." attributes on any element
+  const srcRe = /\bsrc\s*=\s*(?:"([^"]*?)"|'([^']*?)'|([^\s>]+))/gi;
+  let m: RegExpExecArray | null;
+  while ((m = srcRe.exec(html)) !== null) {
+    const url = m[1] ?? m[2] ?? m[3];
+    if (url && /^https?:\/\//i.test(url)) {
+      urls.add(url);
+    }
+  }
+
+  // Match href="..." on any element except navigation/resolution tags (not assets).
+  // Captures the tag name and href value so we can skip them.
+  const hrefRe = /<(\w+)\b[^>]*?\bhref\s*=\s*(?:"([^"]*?)"|'([^']*?)'|([^\s>]+))[^>]*?\/?>/gi;
+  while ((m = hrefRe.exec(html)) !== null) {
+    const tagName = m[1];
+    if (['a', 'base', 'area'].includes(tagName.toLowerCase())) continue;
+    const url = m[2] ?? m[3] ?? m[4];
+    if (url && /^https?:\/\//i.test(url)) {
+      urls.add(url);
+    }
+  }
+
+  // Match CSS url() references (inline styles and <style> blocks)
+  const urlRe = /url\(\s*(?:"([^"]*?)"|'([^']*?)'|([^)"'\s]+))\s*\)/gi;
+  while ((m = urlRe.exec(html)) !== null) {
+    const url = m[1] ?? m[2] ?? m[3];
+    if (url && /^https?:\/\//i.test(url)) {
+      urls.add(url);
+    }
+  }
+
+  return [...urls];
+}
+
+/**
+ * Derive a deterministic filename for a remote asset URL.
+ * Uses a hash of the URL to avoid collisions, preserving the original extension.
+ */
+function assetFilename(url: string): string {
+  const hash = createHash('sha256').update(url).digest('hex').slice(0, HASH_DISPLAY_LENGTH);
+  let ext = '';
+  try {
+    const parsed = new URL(url);
+    ext = extname(parsed.pathname);
+  } catch {
+    // no extension
+  }
+  // Fallback: if no extension or it's too long/weird, drop it
+  if (!ext || ext.length > 10 || !/^\.\w+$/.test(ext)) {
+    ext = '';
+  }
+  return `${hash}${ext}`;
+}
+
+/**
+ * Fetch remote assets referenced in HTML, returning the fetched buffers
+ * and the rewritten HTML with local asset paths. Assets that fail to fetch
+ * are left with their original URLs.
+ */
+export async function materializeAssets(
+  html: string,
+): Promise<{ rewrittenHtml: string; assets: FetchedAsset[] }> {
+  const urls = extractRemoteUrls(html);
+  if (urls.length === 0) {
+    return { rewrittenHtml: html, assets: [] };
+  }
+
+  const assets: FetchedAsset[] = [];
+  // Map from original URL to its local archive path
+  const urlMap = new Map<string, string>();
+
+  await Promise.all(
+    urls.map(async (url) => {
+      try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), ASSET_FETCH_TIMEOUT_MS);
+        let buf: Buffer;
+        try {
+          const resp = await fetch(url, { signal: controller.signal });
+          if (!resp.ok) {
+            bundlerLog.warn({ url, status: resp.status }, 'Failed to fetch asset, keeping original URL');
+            return;
+          }
+          buf = Buffer.from(await resp.arrayBuffer());
+        } finally {
+          clearTimeout(timeout);
+        }
+        const filename = assetFilename(url);
+        const archivePath = `assets/${filename}`;
+        assets.push({ archivePath, data: buf });
+        urlMap.set(url, archivePath);
+      } catch (err) {
+        bundlerLog.warn({ url, err }, 'Failed to fetch asset, keeping original URL');
+      }
+    }),
+  );
+
+  // Rewrite URLs in HTML — replace each occurrence of the original URL with the local path.
+  // Sort by length descending so longer URLs are replaced first, preventing prefix collisions
+  // (e.g. "https://cdn/x" replacing part of "https://cdn/x/y.png").
+  const sortedEntries = [...urlMap.entries()].sort((a, b) => b[0].length - a[0].length);
+  let rewrittenHtml = html;
+  for (const [originalUrl, localPath] of sortedEntries) {
+    // Escape regex special chars in the URL
+    const escaped = originalUrl.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    rewrittenHtml = rewrittenHtml.replace(new RegExp(escaped, 'g'), localPath);
+  }
+
+  return { rewrittenHtml, assets };
+}
+
+export interface BundleResult {
+  bundlePath: string;
+  manifest: AppManifest;
+}
+
+/**
+ * Package an app into a .vellumapp zip archive.
+ *
+ * @param appId - The ID of the app to package (from the app-store).
+ * @param requestSignature - Optional callback to request an Ed25519 signature from the Swift client.
+ *                           If provided, the bundle will be signed and include a signature.json.
+ * @returns The path to the created .vellumapp file and the manifest.
+ * @throws If the app is not found, or the bundle exceeds the size limit.
+ */
+export async function packageApp(
+  appId: string,
+  requestSignature?: SigningCallback,
+): Promise<BundleResult> {
+  const app = getApp(appId);
+  if (!app) {
+    throw new Error(`App not found: ${appId}`);
+  }
+
+  // Build manifest
+  const createdBy = `vellum-assistant/${PACKAGE_VERSION}`;
+  const version = app.version ?? '1.0.0';
+  const contentId = computeContentId(app.name);
+
+  const manifest: AppManifest = {
+    format_version: 1,
+    name: app.name,
+    ...(app.description ? { description: app.description } : {}),
+    ...(app.icon ? { icon: app.icon } : {}),
+    ...(app.preview ? { preview: app.preview } : {}),
+    created_at: new Date().toISOString(),
+    created_by: createdBy,
+    entry: 'index.html',
+    capabilities: [],
+    version,
+    content_id: contentId,
+  };
+
+  // Fetch remote assets and rewrite HTML to reference local copies
+  const { rewrittenHtml, assets: fetchedAssets } = await materializeAssets(app.htmlDefinition);
+
+  // Also materialize assets in additional pages
+  const rewrittenPages: Record<string, string> = {};
+  const pageAssets: FetchedAsset[] = [];
+  if (app.pages) {
+    for (const [filename, content] of Object.entries(app.pages)) {
+      const result = await materializeAssets(content);
+      rewrittenPages[filename] = result.rewrittenHtml;
+      pageAssets.push(...result.assets);
+    }
+  }
+
+  // Deduplicate assets by archive path
+  const allAssetsMap = new Map<string, FetchedAsset>();
+  for (const asset of [...fetchedAssets, ...pageAssets]) {
+    allAssetsMap.set(asset.archivePath, asset);
+  }
+  const allAssets = [...allAssetsMap.values()];
+
+  // Create the zip archive
+  const bundleFilename = `${app.name.replace(/[^a-zA-Z0-9_-]/g, '_')}-${randomUUID().slice(0, SHORT_HASH_LENGTH)}.vellumapp`;
+  const bundlePath = join(tmpdir(), bundleFilename);
+
+  await new Promise<void>((resolve, reject) => {
+    const output = createWriteStream(bundlePath);
+    const archive = archiver('zip', { zlib: { level: 9 } });
+
+    output.on('close', () => resolve());
+    output.on('error', (err: Error) => reject(err));
+    archive.on('error', (err: Error) => reject(err));
+    archive.on('warning', (err: Error) => {
+      // Only reject on fatal warnings
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+        reject(err);
+      }
+    });
+
+    archive.pipe(output);
+
+    // Add manifest.json at root level
+    archive.append(serializeManifest(manifest), { name: 'manifest.json' });
+
+    // Add index.html at root level
+    archive.append(rewrittenHtml, { name: 'index.html' });
+
+    // Add additional pages alongside index.html (with rewritten asset URLs)
+    if (app.pages) {
+      for (const filename of Object.keys(app.pages)) {
+        const content = rewrittenPages[filename] ?? app.pages[filename];
+        archive.append(content, { name: filename });
+      }
+    }
+
+    // Add fetched remote assets
+    for (const asset of allAssets) {
+      archive.append(asset.data, { name: asset.archivePath });
+    }
+
+    archive.finalize();
+  });
+
+  // Sign the bundle if a signing callback is provided
+  if (requestSignature) {
+    try {
+      const signatureJson = await signBundle(bundlePath, requestSignature);
+
+      // Re-open the zip and add signature.json
+      const zipBuffer = await readFile(bundlePath);
+      const zip = await JSZip.loadAsync(zipBuffer);
+      zip.file('signature.json', JSON.stringify(signatureJson, null, 2));
+      const signedBuffer = await zip.generateAsync({
+        type: 'nodebuffer',
+        compression: 'DEFLATE',
+        compressionOptions: { level: 9 },
+      });
+      await writeFile(bundlePath, signedBuffer);
+
+      bundlerLog.info({ appId }, 'Bundle signed successfully');
+    } catch (err) {
+      bundlerLog.warn({ err, appId }, 'Failed to sign bundle, proceeding unsigned');
+    }
+  }
+
+  // Enforce size limit
+  const stats = await stat(bundlePath);
+  if (stats.size > MAX_BUNDLE_SIZE_BYTES) {
+    // Clean up the oversized file
+    const { unlink } = await import('node:fs/promises');
+    await unlink(bundlePath);
+    throw new Error(
+      `Bundle size ${(stats.size / 1024 / 1024).toFixed(1)} MB exceeds the maximum allowed size of 25 MB`,
+    );
+  }
+
+  return { bundlePath, manifest };
+}