@vellumai/assistant 0.3.19 → 0.3.21

package/src/config/__tests__/feature-flag-registry-guard.test.ts

@@ -0,0 +1,179 @@
+/**
+ * Validation guard tests for the unified feature flag registry.
+ *
+ * Ensures structural invariants hold so that both the TS and Swift loaders
+ * can safely consume the registry without runtime surprises.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, test } from 'bun:test';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function getRepoRoot(): string {
+  return join(process.cwd(), '..');
+}
+
+function getRegistryPath(): string {
+  return join(getRepoRoot(), 'meta', 'feature-flags', 'feature-flag-registry.json');
+}
+
+function loadRegistry(): Record<string, unknown> {
+  const raw = readFileSync(getRegistryPath(), 'utf-8');
+  return JSON.parse(raw);
+}
+
+const VALID_SCOPES = new Set(['assistant', 'macos']);
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('unified feature flag registry guard', () => {
+  const registry = loadRegistry();
+  const flags = registry.flags as Record<string, unknown>[];
+
+  // -----------------------------------------------------------------------
+  // version
+  // -----------------------------------------------------------------------
+
+  test('version is a positive integer', () => {
+    expect(typeof registry.version).toBe('number');
+    expect(Number.isInteger(registry.version)).toBe(true);
+    expect(registry.version as number).toBeGreaterThan(0);
+  });
+
+  // -----------------------------------------------------------------------
+  // required fields and types
+  // -----------------------------------------------------------------------
+
+  test('all flags have required fields with correct types', () => {
+    const violations: string[] = [];
+
+    for (let i = 0; i < flags.length; i++) {
+      const flag = flags[i];
+      const prefix = `flags[${i}]`;
+
+      if (typeof flag !== 'object' || !flag || Array.isArray(flag)) {
+        violations.push(`${prefix}: entry is not an object`);
+        continue;
+      }
+
+      if (typeof flag.id !== 'string' || flag.id.length === 0) {
+        violations.push(`${prefix}: missing or non-string 'id'`);
+      }
+      if (typeof flag.scope !== 'string' || flag.scope.length === 0) {
+        violations.push(`${prefix}: missing or non-string 'scope'`);
+      }
+      if (typeof flag.key !== 'string' || flag.key.length === 0) {
+        violations.push(`${prefix}: missing or non-string 'key'`);
+      }
+      if (typeof flag.label !== 'string' || flag.label.length === 0) {
+        violations.push(`${prefix}: missing or non-string 'label'`);
+      }
+      if (typeof flag.description !== 'string' || flag.description.length === 0) {
+        violations.push(`${prefix}: missing or non-string 'description'`);
+      }
+      if (typeof flag.defaultEnabled !== 'boolean') {
+        violations.push(`${prefix}: missing or non-boolean 'defaultEnabled'`);
+      }
+    }
+
+    if (violations.length > 0) {
+      const message = [
+        'Found flags with missing or incorrectly-typed required fields.',
+        '',
+        'Violations:',
+        ...violations.map((v) => `  - ${v}`),
+      ].join('\n');
+
+      expect(violations, message).toEqual([]);
+    }
+  });
+
+  // -----------------------------------------------------------------------
+  // unique ids
+  // -----------------------------------------------------------------------
+
+  test('all id values are unique', () => {
+    const seen = new Set<string>();
+    const duplicates: string[] = [];
+
+    for (const flag of flags) {
+      const id = flag.id as string;
+      if (seen.has(id)) {
+        duplicates.push(id);
+      }
+      seen.add(id);
+    }
+
+    if (duplicates.length > 0) {
+      const message = [
+        'Found duplicate flag id values in the registry.',
+        '',
+        'Duplicates:',
+        ...duplicates.map((d) => `  - ${d}`),
+      ].join('\n');
+
+      expect(duplicates, message).toEqual([]);
+    }
+  });
+
+  // -----------------------------------------------------------------------
+  // unique keys
+  // -----------------------------------------------------------------------
+
+  test('all key values are unique', () => {
+    const seen = new Set<string>();
+    const duplicates: string[] = [];
+
+    for (const flag of flags) {
+      const key = flag.key as string;
+      if (seen.has(key)) {
+        duplicates.push(key);
+      }
+      seen.add(key);
+    }
+
+    if (duplicates.length > 0) {
+      const message = [
+        'Found duplicate flag key values in the registry.',
+        '',
+        'Duplicates:',
+        ...duplicates.map((d) => `  - ${d}`),
+      ].join('\n');
+
+      expect(duplicates, message).toEqual([]);
+    }
+  });
+
+  // -----------------------------------------------------------------------
+  // valid scopes
+  // -----------------------------------------------------------------------
+
+  test('all scope values are valid', () => {
+    const violations: string[] = [];
+
+    for (const flag of flags) {
+      const scope = flag.scope as string;
+      if (!VALID_SCOPES.has(scope)) {
+        violations.push(`flag '${flag.id}' has invalid scope '${scope}' (expected 'assistant' or 'macos')`);
+      }
+    }
+
+    if (violations.length > 0) {
+      const message = [
+        'Found flags with invalid scope values.',
+        '',
+        'Violations:',
+        ...violations.map((v) => `  - ${v}`),
+      ].join('\n');
+
+      expect(violations, message).toEqual([]);
+    }
+  });
+});

package/src/config/assistant-feature-flags.ts

@@ -0,0 +1,162 @@
+/**
+ * Canonical assistant feature-flag resolver.
+ *
+ * Loads default flag values from the unified registry at
+ * `meta/feature-flags/feature-flag-registry.json` and resolves the effective
+ * enabled/disabled state for each declared assistant-scope flag by consulting
+ * (in priority order):
+ *   1. `config.assistantFeatureFlagValues[key]`  (explicit override)
+ *   2. defaults registry `defaultEnabled`         (for declared keys)
+ *   3. `true`                                     (for undeclared keys)
+ *
+ * Key format:
+ *   Canonical:  `feature_flags.<id>.enabled`
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import type { AssistantConfig } from './schema.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface FeatureFlagDefault {
+  defaultEnabled: boolean;
+  description: string;
+  label: string;
+}
+
+export type FeatureFlagDefaultsRegistry = Record<string, FeatureFlagDefault>;
+
+// ---------------------------------------------------------------------------
+// Registry loading (singleton, loaded once)
+// ---------------------------------------------------------------------------
+
+let cachedDefaults: FeatureFlagDefaultsRegistry | undefined;
+
+const REGISTRY_FILENAME = 'feature-flag-registry.json';
+
+function loadDefaultsRegistry(): FeatureFlagDefaultsRegistry {
+  if (cachedDefaults) return cachedDefaults;
+
+  const thisDir = import.meta.dirname ?? __dirname;
+  const envPath = process.env.FEATURE_FLAG_DEFAULTS_PATH?.trim();
+  const candidates = [
+    // Explicit override (primarily for tests / controlled environments)
+    ...(envPath ? [envPath] : []),
+    // Bundled: co-located copy in the same directory as this source file.
+    // Works in Docker / packaged builds where the repo-root `meta/` dir
+    // is not available.
+    join(thisDir, REGISTRY_FILENAME),
+    // Packaged macOS app layout: the daemon binary lives at
+    // <App>.app/Contents/MacOS/vellum-daemon and the registry is copied
+    // to <App>.app/Contents/Resources/ by build.sh. In bun --compile
+    // binaries, import.meta.dirname resolves to /$bunfs/root (virtual),
+    // so we need to resolve relative to the real executable path.
+    join(dirname(process.execPath), '..', 'Resources', REGISTRY_FILENAME),
+    // Development: relative to this source file's directory, walking up
+    // to the repo root to reach `meta/feature-flags/`.
+    join(thisDir, '..', '..', '..', 'meta', 'feature-flags', REGISTRY_FILENAME),
+    // Alternate: from repo root via cwd
+    join(process.cwd(), 'meta', 'feature-flags', REGISTRY_FILENAME),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      try {
+        const raw = readFileSync(candidate, 'utf-8');
+        const parsed = JSON.parse(raw);
+        cachedDefaults = parseRegistryToDefaults(parsed);
+        return cachedDefaults;
+      } catch {
+        // Malformed file — fall through to next candidate
+      }
+    }
+  }
+
+  cachedDefaults = {};
+  return cachedDefaults;
+}
+
+/**
+ * Parse the unified registry JSON into a flat key -> default map,
+ * filtering to assistant-scope flags only.
+ */
+function parseRegistryToDefaults(parsed: unknown): FeatureFlagDefaultsRegistry {
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+
+  const registry = parsed as { version?: number; flags?: unknown[] };
+  if (!Array.isArray(registry.flags)) return {};
+
+  const result: FeatureFlagDefaultsRegistry = {};
+  for (const flag of registry.flags) {
+    if (!flag || typeof flag !== 'object' || Array.isArray(flag)) continue;
+    const entry = flag as Record<string, unknown>;
+    if (entry.scope !== 'assistant') continue;
+    if (typeof entry.key !== 'string') continue;
+    if (typeof entry.defaultEnabled !== 'boolean') continue;
+
+    result[entry.key as string] = {
+      defaultEnabled: entry.defaultEnabled,
+      description: typeof entry.description === 'string' ? entry.description : '',
+      label: typeof entry.label === 'string' ? entry.label : '',
+    };
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve whether an assistant feature flag is enabled.
+ *
+ * Resolution order:
+ *   1. `config.assistantFeatureFlagValues[key]`  (explicit override)
+ *   2. defaults registry `defaultEnabled`         (for declared assistant-scope keys)
+ *   3. `true`                                     (for undeclared keys with no override)
+ */
+export function isAssistantFeatureFlagEnabled(key: string, config: AssistantConfig): boolean {
+  const defaults = loadDefaultsRegistry();
+  const declared = defaults[key];
+
+  // 1. Check canonical section
+  const newValues = (config as AssistantConfigWithFeatureFlags).assistantFeatureFlagValues;
+  if (newValues) {
+    const explicit = newValues[key];
+    if (typeof explicit === 'boolean') return explicit;
+  }
+
+  // 2. For declared keys, use the registry default
+  if (declared) {
+    return declared.defaultEnabled;
+  }
+
+  // 3. Undeclared keys with no persisted override default to enabled
+  return true;
+}
+
+/**
+ * Return the loaded defaults registry (for introspection/tooling).
+ */
+export function getAssistantFeatureFlagDefaults(): FeatureFlagDefaultsRegistry {
+  return loadDefaultsRegistry();
+}
+
+/**
+ * Reset the cached defaults registry. Intended for tests only.
+ */
+export function _resetDefaultsCache(): void {
+  cachedDefaults = undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Internal type augmentation for the new config field
+// ---------------------------------------------------------------------------
+
+interface AssistantConfigWithFeatureFlags extends AssistantConfig {
+  assistantFeatureFlagValues?: Record<string, boolean>;
+}

package/src/config/bundled-skills/api-mapping/icon.svg

@@ -0,0 +1,18 @@
+<svg viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
+  <rect width="16" height="16" fill="#0f172a"/>
+  <rect x="2" y="2" width="12" height="12" fill="#1e293b"/>
+  <rect x="3" y="3" width="10" height="10" fill="#0f172a" stroke="#3b82f6" stroke-width="1"/>
+  <rect x="4" y="4" width="2" height="2" fill="#3b82f6"/>
+  <rect x="10" y="4" width="2" height="2" fill="#3b82f6"/>
+  <rect x="4" y="10" width="2" height="2" fill="#3b82f6"/>
+  <rect x="10" y="10" width="2" height="2" fill="#3b82f6"/>
+  <line x1="5" y1="5" x2="11" y2="5" stroke="#10b981" stroke-width="1"/>
+  <line x1="5" y1="5" x2="5" y2="11" stroke="#10b981" stroke-width="1"/>
+  <line x1="11" y1="5" x2="11" y2="11" stroke="#10b981" stroke-width="1"/>
+  <line x1="5" y1="11" x2="11" y2="11" stroke="#10b981" stroke-width="1"/>
+  <rect x="7" y="7" width="2" height="2" fill="#f59e0b"/>
+  <line x1="5" y1="8" x2="7" y2="8" stroke="#60a5fa" stroke-width="1"/>
+  <line x1="9" y1="8" x2="11" y2="8" stroke="#60a5fa" stroke-width="1"/>
+  <line x1="8" y1="5" x2="8" y2="7" stroke="#60a5fa" stroke-width="1"/>
+  <line x1="8" y1="9" x2="8" y2="11" stroke="#60a5fa" stroke-width="1"/>
+</svg>

package/src/config/bundled-skills/messaging/TOOLS.json

@@ -256,6 +256,36 @@
       "executor": "tools/slack-add-reaction.ts",
       "execution_target": "host"
     },
+    {
+      "name": "slack_delete_message",
+      "description": "Delete a Slack message posted by the bot. Include a confidence score (0-1).",
+      "category": "messaging",
+      "risk": "high",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "channel": {
+            "type": "string",
+            "description": "Slack channel ID"
+          },
+          "timestamp": {
+            "type": "string",
+            "description": "Message timestamp (ts) to delete"
+          },
+          "confidence": {
+            "type": "number",
+            "description": "Confidence score (0-1) for this action"
+          }
+        },
+        "required": [
+          "channel",
+          "timestamp",
+          "confidence"
+        ]
+      },
+      "executor": "tools/slack-delete-message.ts",
+      "execution_target": "host"
+    },
     {
       "name": "slack_leave_channel",
       "description": "Leave a Slack channel. Include a confidence score (0-1).",

package/src/config/bundled-skills/messaging/tools/slack-delete-message.ts

@@ -0,0 +1,24 @@
+import { deleteMessage } from '../../../../messaging/providers/slack/client.js';
+import { getMessagingProvider } from '../../../../messaging/registry.js';
+import { withValidToken } from '../../../../security/token-manager.js';
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { err, ok } from './shared.js';
+
+export async function run(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+  const channel = input.channel as string;
+  const timestamp = input.timestamp as string;
+
+  if (!channel || !timestamp) {
+    return err('channel and timestamp are both required.');
+  }
+
+  try {
+    const provider = getMessagingProvider('slack');
+    return withValidToken(provider.credentialService, async (token) => {
+      await deleteMessage(token, channel, timestamp);
+      return ok(`Message deleted.`);
+    });
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+}

package/src/config/bundled-skills/notifications/SKILL.md

@@ -14,7 +14,7 @@ Use `send_notification` for user-facing alerts and notifications. This tool rout
 
 ## Deduplication (`dedupe_key`)
 
-- `dedupe_key` suppresses duplicate signals. A second notification with the same key is **dropped entirely** within a **1-hour window**. After the window expires, the same key is accepted again.
+- `dedupe_key` suppresses duplicate signals **permanently**. A second notification with the same key is **dropped entirely** for the lifetime of the assistant's event store. Once a key has been used, it cannot be reused — any future notification with the same key will be silently discarded.
 - Never reuse a `dedupe_key` across logically distinct notifications, even if they are related. The key means "this exact event already fired," not "these events are in the same category."
 - If you omit `dedupe_key`, the LLM decision engine may generate one automatically based on signal context. This means even keyless signals can be deduplicated if the engine considers them duplicates of a recent event.
 

package/src/config/bundled-skills/reminder/SKILL.md

@@ -15,12 +15,34 @@ Create, list, and cancel one-time reminders. Reminders fire at a specific future
 
 Control how the reminder is delivered at trigger time with `routing_intent`:
 
-- **single_channel** (default) — deliver to one best channel
+- **single_channel** — deliver to one best channel
 - **multi_channel** — deliver to a subset of channels
-- **all_channels** — deliver to every available channel
+- **all_channels** (default) — deliver to every available channel
 
 Optionally pass `routing_hints` (a JSON object) to influence routing decisions (e.g. preferred channels, exclusions). When omitted, defaults to `{}`.
 
+### Routing Defaults
+
+Use the following heuristics to pick `routing_intent`:
+
+- **Default to `all_channels`** for most reminders. Users setting reminders usually want to be notified wherever they are, and redundant notifications are less harmful than missed ones.
+- **Use `single_channel`** only when the user explicitly specifies a single channel (e.g. "remind me on Telegram") or the reminder is low-stakes and noise reduction matters.
+- **Check `user_message_channel`** from the turn context. If the user is currently active on a specific channel (e.g. `vellum`), always include that channel. Pass it as a routing hint:
+  ```
+  routing_hints: { preferred_channels: ["vellum"] }
+  routing_intent: "all_channels"
+  ```
+- **Never use `single_channel` as a passive default.** If you haven't thought about which channel to use, use `all_channels`.
+
+### Examples
+
+| Scenario | routing_intent | routing_hints |
+|---|---|---|
+| User sets reminder from desktop app | `all_channels` | `{ preferred_channels: ["vellum"] }` |
+| User says "remind me on Telegram" | `single_channel` | `{ preferred_channels: ["telegram"] }` |
+| User sets reminder from Telegram | `all_channels` | `{ preferred_channels: ["telegram"] }` |
+| No channel preference expressed | `all_channels` | `{}` |
+
 ## Usage Notes
 
 - Use reminders ONLY for time-triggered notifications (e.g. "remind me at 3pm", "remind me in 2 hours").
@@ -28,3 +50,28 @@ Optionally pass `routing_hints` (a JSON object) to influence routing decisions (
 - For task tracking ("add to my tasks", "add to my queue"), use task_list_add instead.
 - `fire_at` must be a strict ISO 8601 timestamp with timezone offset or Z (e.g. `2025-03-15T09:00:00-05:00` or `2025-03-15T09:00:00Z`). Ambiguous timestamps without timezone info will be rejected.
 - `label` is a short human-readable summary shown in the notification.
+
+### Anchored & Ambiguous Relative Time
+
+Phrases like "at the 45 minute mark", "at the top of the hour", "on the half-hour", "at noon", "20 minutes in", or "when I hit an hour" are **clock-position or anchored relative time** expressions. Do NOT treat them as offsets from now.
+
+**Resolution rules (in priority order):**
+
+1. **Clock-position expressions** — map directly to a wall-clock time:
+   - "top of the hour" / "on the hour" → next :00 (e.g. 10:00 AM)
+   - "the X minute mark" / "at :XX" → current hour's :XX; if already past, advance one hour
+   - "the half-hour mark" / "half past" → nearest upcoming :30
+   - "noon" / "midnight" → 12:00 PM or 12:00 AM today; if past, tomorrow
+   - "quarter past" / "quarter to" → :15 or :45 of current or next hour
+
+2. **Session-anchored expressions** — if the user mentioned a start time earlier in conversation ("I got here at 9", "meeting started at 2pm"), compute `start_time + offset`.
+
+3. **Ask only if truly ambiguous** — if neither rule 1 nor rule 2 resolves, ask: "Do you mean [clock time] or [X minutes from now]?" Never silently default to "from now."
+
+**Examples:**
+- "at the 45 min mark" (now: 9:39) → 9:45 AM
+- "at the 45 min mark" (now: 9:50) → 10:45 AM
+- "top of the hour" (now: 9:39) → 10:00 AM
+- "at noon" → 12:00 PM today
+- "20 minutes in, I started at 2pm" → 2:20 PM
+- "at the hour mark" with no start time → ask for clarification

package/src/config/bundled-skills/time-based-actions/SKILL.md

@@ -55,6 +55,31 @@ When the user says "in X minutes/hours", compute the ISO 8601 timestamp yourself
 - Format as ISO 8601 with timezone: `2025-03-15T09:05:00-05:00`
 - Pass to `reminder_create` as `fire_at`
 
+### Anchored & Ambiguous Relative Time
+
+Phrases like "at the 45 minute mark", "at the top of the hour", "on the half-hour", "at noon", "20 minutes in", or "when I hit an hour" are **clock-position or anchored relative time** expressions. Do NOT treat them as offsets from now.
+
+**Resolution rules (in priority order):**
+
+1. **Clock-position expressions** — map directly to a wall-clock time:
+   - "top of the hour" / "on the hour" → next :00 (e.g. 10:00 AM)
+   - "the X minute mark" / "at :XX" → current hour's :XX; if already past, advance one hour
+   - "the half-hour mark" / "half past" → nearest upcoming :30
+   - "noon" / "midnight" → 12:00 PM or 12:00 AM today; if past, tomorrow
+   - "quarter past" / "quarter to" → :15 or :45 of current or next hour
+
+2. **Session-anchored expressions** — if the user mentioned a start time earlier in conversation ("I got here at 9", "meeting started at 2pm"), compute `start_time + offset`.
+
+3. **Ask only if truly ambiguous** — if neither rule 1 nor rule 2 resolves, ask: "Do you mean [clock time] or [X minutes from now]?" Never silently default to "from now."
+
+**Examples:**
+- "at the 45 min mark" (now: 9:39) → 9:45 AM
+- "at the 45 min mark" (now: 9:50) → 10:45 AM
+- "top of the hour" (now: 9:39) → 10:00 AM
+- "at noon" → 12:00 PM today
+- "20 minutes in, I started at 2pm" → 2:20 PM
+- "at the hour mark" with no start time → ask for clarification
+
 ## "Remind me to X" Disambiguation
 
 The word "remind" is ambiguous. Route based on whether a time is specified:
@@ -77,12 +102,34 @@ Use `notify` for simple alerts. Use `execute` when the reminder should trigger t
 ## Reminder Routing
 
 `reminder_create` supports a `routing_intent` parameter that controls how the reminder is delivered at trigger time:
-- **`single_channel`** (default) — deliver to one best channel
+- **`single_channel`** — deliver to one best channel
 - **`multi_channel`** — deliver to a subset of channels
-- **`all_channels`** — deliver to every available channel
+- **`all_channels`** (default) — deliver to every available channel
 
 You can also pass `routing_hints` (a JSON object) to influence routing decisions (e.g. preferred channels, exclusions).
 
+### Routing Defaults
+
+Use the following heuristics to pick `routing_intent`:
+
+- **Default to `all_channels`** for most reminders. Users setting reminders usually want to be notified wherever they are, and redundant notifications are less harmful than missed ones.
+- **Use `single_channel`** only when the user explicitly specifies a single channel (e.g. "remind me on Telegram") or the reminder is low-stakes and noise reduction matters.
+- **Check `user_message_channel`** from the turn context. If the user is currently active on a specific channel (e.g. `vellum`), always include that channel. Pass it as a routing hint:
+  ```
+  routing_hints: { preferred_channels: ["vellum"] }
+  routing_intent: "all_channels"
+  ```
+- **Never use `single_channel` as a passive default.** If you haven't thought about which channel to use, use `all_channels`.
+
+### Examples
+
+| Scenario | routing_intent | routing_hints |
+|---|---|---|
+| User sets reminder from desktop app | `all_channels` | `{ preferred_channels: ["vellum"] }` |
+| User says "remind me on Telegram" | `single_channel` | `{ preferred_channels: ["telegram"] }` |
+| User sets reminder from Telegram | `all_channels` | `{ preferred_channels: ["telegram"] }` |
+| No channel preference expressed | `all_channels` | `{}` |
+
 ## Tool Summary
 
 | Tool | Timing | Recurrence | Purpose |