@vellumai/assistant 0.3.19 → 0.3.20

package/src/__tests__/session-runtime-assembly.test.ts

@@ -335,11 +335,6 @@ describe('buildChannelAwarenessSection', () => {
     expect(section).toContain('computer-control permissions on non-dashboard');
   });
 
-  test('includes guardian context contract for channel actors', () => {
-    const section = buildChannelAwarenessSection();
-    expect(section).toContain('<guardian_context>');
-    expect(section).toContain('Never infer guardian status');
-  });
 });
 
 // ---------------------------------------------------------------------------
@@ -569,6 +564,39 @@ describe('injectGuardianContext', () => {
     expect(text).toContain('source_channel: sms');
     expect(text).toContain('</guardian_context>');
   });
+
+  test('includes behavioral guidance for non-guardian actors', () => {
+    const ctx: GuardianRuntimeContext = {
+      sourceChannel: 'telegram',
+      actorRole: 'non-guardian',
+      guardianExternalUserId: 'guardian-user-1',
+      guardianChatId: 'chat-1',
+      requesterIdentifier: '@someone',
+      requesterExternalUserId: 'other-user-1',
+      requesterChatId: 'chat-2',
+    };
+
+    const result = injectGuardianContext(baseUserMessage, ctx);
+    const text = (result.content[0] as { type: 'text'; text: string }).text;
+    expect(text).toContain('non-guardian account');
+    expect(text).toContain('Do not explain the verification system');
+  });
+
+  test('omits non-guardian behavioral guidance for guardian actors', () => {
+    const ctx: GuardianRuntimeContext = {
+      sourceChannel: 'telegram',
+      actorRole: 'guardian',
+      guardianExternalUserId: 'guardian-user-1',
+      guardianChatId: 'chat-1',
+      requesterIdentifier: '@guardian',
+      requesterExternalUserId: 'guardian-user-1',
+      requesterChatId: 'chat-1',
+    };
+
+    const result = injectGuardianContext(baseUserMessage, ctx);
+    const text = (result.content[0] as { type: 'text'; text: string }).text;
+    expect(text).not.toContain('non-guardian account');
+  });
 });
 
 describe('stripGuardianContext', () => {

package/src/__tests__/skill-feature-flags-integration.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Integration tests for skill feature flag enforcement at system prompt,
+ * skill_load, and session-skill-tools projection layers.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+
+// ---------------------------------------------------------------------------
+// Test-scoped temp directory and config state
+// ---------------------------------------------------------------------------
+
+const TEST_DIR = join(tmpdir(), `vellum-skill-flags-test-${crypto.randomUUID()}`);
+
+let currentConfig: Record<string, unknown> = {
+  sandbox: { enabled: false, backend: 'native' },
+  featureFlags: {},
+};
+
+const DECLARED_SKILL_ID = 'hatch-new-assistant';
+const DECLARED_LEGACY_KEY = 'skills.hatch-new-assistant.enabled';
+
+mock.module('../util/platform.js', () => ({
+  getRootDir: () => TEST_DIR,
+  getDataDir: () => TEST_DIR,
+  getWorkspaceDir: () => TEST_DIR,
+  getWorkspaceConfigPath: () => join(TEST_DIR, 'config.json'),
+  getWorkspaceSkillsDir: () => join(TEST_DIR, 'skills'),
+  getWorkspaceHooksDir: () => join(TEST_DIR, 'hooks'),
+  getWorkspacePromptPath: (file: string) => join(TEST_DIR, file),
+  ensureDataDir: () => {},
+  getSocketPath: () => join(TEST_DIR, 'vellum.sock'),
+  getPidPath: () => join(TEST_DIR, 'vellum.pid'),
+  getDbPath: () => join(TEST_DIR, 'data', 'assistant.db'),
+  getLogPath: () => join(TEST_DIR, 'logs', 'vellum.log'),
+  getHistoryPath: () => join(TEST_DIR, 'history'),
+  getHooksDir: () => join(TEST_DIR, 'hooks'),
+  getIpcBlobDir: () => join(TEST_DIR, 'ipc-blobs'),
+  getSandboxRootDir: () => join(TEST_DIR, 'sandbox'),
+  getSandboxWorkingDir: () => TEST_DIR,
+  getInterfacesDir: () => join(TEST_DIR, 'interfaces'),
+  isMacOS: () => false,
+  isLinux: () => false,
+  isWindows: () => false,
+  getPlatformName: () => 'linux',
+  getClipboardCommand: () => null,
+  removeSocketFile: () => {},
+  migratePath: () => {},
+  migrateToWorkspaceLayout: () => {},
+  migrateToDataLayout: () => {},
+}));
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => new Proxy({} as Record<string, unknown>, {
+    get: () => () => {},
+  }),
+  isDebug: () => false,
+  truncateForLog: (v: string) => v,
+}));
+
+mock.module('../config/loader.js', () => ({
+  getConfig: () => currentConfig,
+}));
+
+mock.module('../config/user-reference.js', () => ({
+  resolveUserReference: () => 'TestUser',
+}));
+
+mock.module('../security/parental-control-store.js', () => ({
+  getParentalControlSettings: () => ({ enabled: false, contentRestrictions: [], blockedToolCategories: [] }),
+}));
+
+mock.module('../tools/credentials/metadata-store.js', () => ({
+  listCredentialMetadata: () => [],
+}));
+
+const { buildSystemPrompt } = await import('../config/system-prompt.js');
+
+// ---------------------------------------------------------------------------
+// Setup / Teardown
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  mkdirSync(TEST_DIR, { recursive: true });
+  // Reset config to defaults before each test
+  currentConfig = {
+    sandbox: { enabled: false, backend: 'native' },
+    featureFlags: {},
+  };
+});
+
+afterEach(() => {
+  if (existsSync(TEST_DIR)) {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createSkillOnDisk(id: string, name: string, description: string): void {
+  const skillsDir = join(TEST_DIR, 'skills');
+  mkdirSync(join(skillsDir, id), { recursive: true });
+  writeFileSync(
+    join(skillsDir, id, 'SKILL.md'),
+    `---\nname: "${name}"\ndescription: "${description}"\n---\n\nInstructions for ${id}.\n`,
+  );
+  // Ensure SKILLS.md index references the skill
+  const indexPath = join(skillsDir, 'SKILLS.md');
+  const existing = existsSync(indexPath) ? readFileSync(indexPath, 'utf-8') : '';
+  writeFileSync(indexPath, existing + `- ${id}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// System prompt — feature flag filtering
+// ---------------------------------------------------------------------------
+
+describe('buildSystemPrompt feature flag filtering', () => {
+  test('flag OFF skill does not appear in <available_skills> section', () => {
+    createSkillOnDisk(DECLARED_SKILL_ID, 'Hatch New Assistant', 'Toggle hatch new assistant behavior');
+    createSkillOnDisk('twitter', 'Twitter', 'Post to X/Twitter');
+
+    currentConfig = {
+      sandbox: { enabled: false, backend: 'native' },
+      featureFlags: { [DECLARED_LEGACY_KEY]: false },
+    };
+
+    const result = buildSystemPrompt();
+
+    // twitter should be visible, declared flagged skill should not
+    expect(result).toContain('id="twitter"');
+    expect(result).not.toContain(`id="${DECLARED_SKILL_ID}"`);
+  });
+
+  test('all skills visible when featureFlags is empty', () => {
+    createSkillOnDisk(DECLARED_SKILL_ID, 'Hatch New Assistant', 'Toggle hatch new assistant behavior');
+    createSkillOnDisk('twitter', 'Twitter', 'Post to X/Twitter');
+
+    currentConfig = {
+      sandbox: { enabled: false, backend: 'native' },
+      featureFlags: {},
+    };
+
+    const result = buildSystemPrompt();
+
+    expect(result).toContain(`id="${DECLARED_SKILL_ID}"`);
+    expect(result).toContain('id="twitter"');
+  });
+
+  test('flagged-off skills hidden even when all workspace skill flags are OFF', () => {
+    createSkillOnDisk(DECLARED_SKILL_ID, 'Hatch New Assistant', 'Toggle hatch new assistant behavior');
+    createSkillOnDisk('twitter', 'Twitter', 'Post to X/Twitter');
+
+    currentConfig = {
+      sandbox: { enabled: false, backend: 'native' },
+      featureFlags: {
+        [DECLARED_LEGACY_KEY]: false,
+        'skills.twitter.enabled': false,
+      },
+    };
+
+    const result = buildSystemPrompt();
+
+    // Both are hidden: declared skill via registry, undeclared via persisted override.
+    expect(result).not.toContain(`id="${DECLARED_SKILL_ID}"`);
+    expect(result).not.toContain('id="twitter"');
+  });
+});

package/src/__tests__/skill-feature-flags.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, test } from 'bun:test';
+
+import { isAssistantFeatureFlagEnabled } from '../config/assistant-feature-flags.js';
+import type { AssistantConfig } from '../config/schema.js';
+import { isSkillFeatureEnabled, resolveSkillStates } from '../config/skill-state.js';
+import type { SkillSummary } from '../config/skills.js';
+
+const DECLARED_FLAG_KEY = 'feature_flags.hatch-new-assistant.enabled';
+const DECLARED_SKILL_ID = 'hatch-new-assistant';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Create a minimal AssistantConfig with optional feature flag values. */
+function makeConfig(overrides: Partial<AssistantConfig> = {}): AssistantConfig {
+  return {
+    skills: {
+      entries: {},
+      load: { extraDirs: [], watch: true, watchDebounceMs: 250 },
+      install: { nodeManager: 'npm' },
+      allowBundled: null,
+      remoteProviders: { skillssh: { enabled: true }, clawhub: { enabled: true } },
+      remotePolicy: { blockSuspicious: true, blockMalware: true, maxSkillsShRisk: 'medium' },
+    },
+    ...overrides,
+  } as AssistantConfig;
+}
+
+/** Create a minimal SkillSummary for testing. */
+function makeSkill(id: string, source: 'bundled' | 'managed' = 'bundled'): SkillSummary {
+  return {
+    id,
+    name: `${id} skill`,
+    description: `Description for ${id}`,
+    directoryPath: `/fake/skills/${id}`,
+    skillFilePath: `/fake/skills/${id}/SKILL.md`,
+    bundled: source === 'bundled',
+    userInvocable: true,
+    disableModelInvocation: false,
+    source,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// isSkillFeatureEnabled (legacy wrapper — backward compat)
+// ---------------------------------------------------------------------------
+
+describe('isSkillFeatureEnabled', () => {
+  test('returns true when no flag overrides', () => {
+    const config = makeConfig();
+    expect(isSkillFeatureEnabled(DECLARED_SKILL_ID, config)).toBe(true);
+  });
+
+  test('returns true when skill key is explicitly true', () => {
+    const config = makeConfig({
+      assistantFeatureFlagValues: { [DECLARED_FLAG_KEY]: true },
+    });
+    expect(isSkillFeatureEnabled(DECLARED_SKILL_ID, config)).toBe(true);
+  });
+
+  test('returns false when skill key is explicitly false', () => {
+    const config = makeConfig({
+      assistantFeatureFlagValues: { [DECLARED_FLAG_KEY]: false },
+    });
+    expect(isSkillFeatureEnabled(DECLARED_SKILL_ID, config)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isAssistantFeatureFlagEnabled (full canonical key)
+// ---------------------------------------------------------------------------
+
+describe('isAssistantFeatureFlagEnabled', () => {
+  test('returns true for unknown flags (open by default)', () => {
+    const config = makeConfig();
+    expect(isAssistantFeatureFlagEnabled('feature_flags.unknown.enabled', config)).toBe(true);
+  });
+
+  test('assistantFeatureFlagValues overrides registry default', () => {
+    const config = {
+      ...makeConfig(),
+      assistantFeatureFlagValues: { [DECLARED_FLAG_KEY]: false },
+    } as AssistantConfig;
+    expect(isAssistantFeatureFlagEnabled(DECLARED_FLAG_KEY, config)).toBe(false);
+  });
+
+  test('falls back to registry default when no override', () => {
+    const config = makeConfig();
+    // hatch-new-assistant defaults to true in the registry
+    expect(isAssistantFeatureFlagEnabled(DECLARED_FLAG_KEY, config)).toBe(true);
+  });
+
+  test('respects persisted overrides for undeclared keys', () => {
+    const config = makeConfig({
+      assistantFeatureFlagValues: { 'feature_flags.browser.enabled': false },
+    });
+    expect(isAssistantFeatureFlagEnabled('feature_flags.browser.enabled', config)).toBe(false);
+  });
+
+  test('undeclared keys with no persisted override default to enabled', () => {
+    const config = makeConfig();
+    expect(isAssistantFeatureFlagEnabled('feature_flags.browser.enabled', config)).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveSkillStates — feature flag filtering
+// ---------------------------------------------------------------------------
+
+describe('resolveSkillStates with feature flags', () => {
+  test('flag OFF skill does not appear in resolved list', () => {
+    const catalog = [makeSkill(DECLARED_SKILL_ID), makeSkill('twitter')];
+    const config = makeConfig({
+      assistantFeatureFlagValues: { [DECLARED_FLAG_KEY]: false },
+    });
+
+    const resolved = resolveSkillStates(catalog, config);
+    const ids = resolved.map((r) => r.summary.id);
+
+    expect(ids).not.toContain(DECLARED_SKILL_ID);
+    expect(ids).toContain('twitter');
+  });
+
+  test('flag ON skill appears normally', () => {
+    const catalog = [makeSkill(DECLARED_SKILL_ID), makeSkill('twitter')];
+    const config = makeConfig({
+      assistantFeatureFlagValues: {
+        [DECLARED_FLAG_KEY]: true,
+        'feature_flags.twitter.enabled': true,
+      },
+    });
+
+    const resolved = resolveSkillStates(catalog, config);
+    const ids = resolved.map((r) => r.summary.id);
+
+    expect(ids).toContain(DECLARED_SKILL_ID);
+    expect(ids).toContain('twitter');
+  });
+
+  test('missing flag key defaults to enabled', () => {
+    const catalog = [makeSkill(DECLARED_SKILL_ID)];
+    const config = makeConfig();
+
+    const resolved = resolveSkillStates(catalog, config);
+    expect(resolved.length).toBe(1);
+    expect(resolved[0].summary.id).toBe(DECLARED_SKILL_ID);
+  });
+
+  test('feature flag OFF takes precedence over user-enabled config entry', () => {
+    const catalog = [makeSkill(DECLARED_SKILL_ID)];
+    const config = makeConfig({
+      assistantFeatureFlagValues: { [DECLARED_FLAG_KEY]: false },
+      skills: {
+        entries: { [DECLARED_SKILL_ID]: { enabled: true } },
+        load: { extraDirs: [], watch: true, watchDebounceMs: 250 },
+        install: { nodeManager: 'npm' },
+        allowBundled: null,
+        remoteProviders: { skillssh: { enabled: true }, clawhub: { enabled: true } },
+        remotePolicy: { blockSuspicious: true, blockMalware: true, maxSkillsShRisk: 'medium' },
+      },
+    });
+
+    const resolved = resolveSkillStates(catalog, config);
+    // The skill should not appear at all — feature flag is a higher-priority gate
+    expect(resolved.length).toBe(0);
+  });
+
+  test('multiple skills with mixed flags — persisted overrides respected', () => {
+    const catalog = [
+      makeSkill(DECLARED_SKILL_ID),
+      makeSkill('twitter'),
+      makeSkill('deploy'),
+    ];
+    const config = makeConfig({
+      assistantFeatureFlagValues: {
+        [DECLARED_FLAG_KEY]: false,
+        'feature_flags.deploy.enabled': false,
+      },
+    });
+
+    const resolved = resolveSkillStates(catalog, config);
+    const ids = resolved.map((r) => r.summary.id);
+
+    // Both declared (hatch-new-assistant) and undeclared (deploy) skills with
+    // persisted false overrides are filtered out; only twitter remains.
+    expect(ids).toEqual(['twitter']);
+  });
+});

package/src/__tests__/skill-load-feature-flag.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Tests that skill_load rejects loading a skill whose feature flag is OFF
+ * with a deterministic error message.
+ */
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+
+const TEST_DIR = join(tmpdir(), `vellum-skill-load-flag-test-${crypto.randomUUID()}`);
+
+let currentConfig: Record<string, unknown> = {
+  featureFlags: {},
+};
+
+const DECLARED_SKILL_ID = 'hatch-new-assistant';
+const DECLARED_LEGACY_KEY = 'skills.hatch-new-assistant.enabled';
+
+const platformOverrides: Record<string, (...args: unknown[]) => unknown> = {
+  getRootDir: () => TEST_DIR,
+  getDataDir: () => TEST_DIR,
+  ensureDataDir: () => {},
+  getSocketPath: () => join(TEST_DIR, 'vellum.sock'),
+  getPidPath: () => join(TEST_DIR, 'vellum.pid'),
+  getDbPath: () => join(TEST_DIR, 'data', 'assistant.db'),
+  getLogPath: () => join(TEST_DIR, 'logs', 'vellum.log'),
+  getWorkspaceDir: () => join(TEST_DIR, 'workspace'),
+  getWorkspaceSkillsDir: () => join(TEST_DIR, 'skills'),
+  getWorkspaceConfigPath: () => join(TEST_DIR, 'workspace', 'config.json'),
+  getWorkspaceHooksDir: () => join(TEST_DIR, 'workspace', 'hooks'),
+  getWorkspacePromptPath: (f: unknown) => join(TEST_DIR, 'workspace', String(f)),
+  getInterfacesDir: () => join(TEST_DIR, 'interfaces'),
+  getHooksDir: () => join(TEST_DIR, 'hooks'),
+  getIpcBlobDir: () => join(TEST_DIR, 'blobs'),
+  getSandboxRootDir: () => join(TEST_DIR, 'sandbox'),
+  getSandboxWorkingDir: () => join(TEST_DIR, 'sandbox', 'work'),
+  getHistoryPath: () => join(TEST_DIR, 'history'),
+  getSessionTokenPath: () => join(TEST_DIR, 'session-token'),
+  readSessionToken: () => null,
+  getClipboardCommand: () => null,
+  isMacOS: () => process.platform === 'darwin',
+  isLinux: () => process.platform === 'linux',
+  isWindows: () => process.platform === 'win32',
+  getPlatformName: () => process.platform,
+  migratePath: () => {},
+  migrateToWorkspaceLayout: () => {},
+  migrateToDataLayout: () => {},
+  removeSocketFile: () => {},
+};
+mock.module('../util/platform.js', () => platformOverrides);
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => new Proxy({} as Record<string, unknown>, {
+    get: () => () => {},
+  }),
+}));
+
+mock.module('../config/loader.js', () => ({
+  getConfig: () => currentConfig,
+}));
+
+await import('../tools/skills/load.js');
+const { getTool } = await import('../tools/registry.js');
+
+function writeSkill(skillId: string, name: string, description: string, body: string): void {
+  const skillDir = join(TEST_DIR, 'skills', skillId);
+  mkdirSync(skillDir, { recursive: true });
+  writeFileSync(
+    join(skillDir, 'SKILL.md'),
+    `---\nname: "${name}"\ndescription: "${description}"\n---\n\n${body}\n`,
+  );
+}
+
+async function executeSkillLoad(input: Record<string, unknown>): Promise<{ content: string; isError: boolean }> {
+  const tool = getTool('skill_load');
+  if (!tool) throw new Error('skill_load tool was not registered');
+
+  const result = await tool.execute(input, {
+    workingDir: '/tmp',
+    sessionId: 'session-1',
+    conversationId: 'conversation-1',
+  });
+  return { content: result.content, isError: result.isError };
+}
+
+describe('skill_load feature flag enforcement', () => {
+  beforeEach(() => {
+    mkdirSync(join(TEST_DIR, 'skills'), { recursive: true });
+    currentConfig = { featureFlags: {} };
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+  });
+
+  test('returns deterministic error for flag OFF skill', async () => {
+    writeSkill(DECLARED_SKILL_ID, 'Hatch New Assistant', 'Toggle hatch new assistant behavior', 'Use the feature.');
+    writeFileSync(join(TEST_DIR, 'skills', 'SKILLS.md'), `- ${DECLARED_SKILL_ID}\n`);
+
+    currentConfig = {
+      featureFlags: { [DECLARED_LEGACY_KEY]: false },
+    };
+
+    const result = await executeSkillLoad({ skill: DECLARED_SKILL_ID });
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('disabled by feature flag');
+    expect(result.content).toContain(DECLARED_SKILL_ID);
+  });
+
+  test('loads skill normally when flag is ON', async () => {
+    writeSkill(DECLARED_SKILL_ID, 'Hatch New Assistant', 'Toggle hatch new assistant behavior', 'Use the feature.');
+    writeFileSync(join(TEST_DIR, 'skills', 'SKILLS.md'), `- ${DECLARED_SKILL_ID}\n`);
+
+    currentConfig = {
+      featureFlags: { [DECLARED_LEGACY_KEY]: true },
+    };
+
+    const result = await executeSkillLoad({ skill: DECLARED_SKILL_ID });
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain('Skill: Hatch New Assistant');
+  });
+
+  test('loads skill normally when flag key is absent (defaults to enabled)', async () => {
+    writeSkill(DECLARED_SKILL_ID, 'Hatch New Assistant', 'Toggle hatch new assistant behavior', 'Use the feature.');
+    writeFileSync(join(TEST_DIR, 'skills', 'SKILLS.md'), `- ${DECLARED_SKILL_ID}\n`);
+
+    currentConfig = {
+      featureFlags: {},
+    };
+
+    const result = await executeSkillLoad({ skill: DECLARED_SKILL_ID });
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain('Skill: Hatch New Assistant');
+  });
+});

package/src/__tests__/skill-mirror-parity.test.ts

@@ -36,6 +36,7 @@ const TOPLEVEL_CATALOG = join(TOPLEVEL_SKILLS_DIR, 'catalog.json');
 // ---------------------------------------------------------------------------
 
 const TOPLEVEL_ONLY_SKILLS = new Set([
+  'doordash',
   'google-oauth-setup',
   'notion',
   'notion-oauth-setup',