@soleri/core 9.3.1 → 9.5.0

package/src/curator/curator.test.ts

@@ -647,4 +647,96 @@ describe('Curator', () => {
       expect(result.metrics.tagHealth).toBeLessThan(1);
     });
   });
+
+  // ─── Duplicate Dismissal ──────────────────────────────────────
+
+  describe('Duplicate Dismissal', () => {
+    it('dismissDuplicate stores a pair and detectDuplicates filters it out', () => {
+      // Add two similar entries that will be flagged as duplicates
+      vault.add(
+        makeEntry({
+          id: 'dup-a',
+          title: 'React hook cleanup pattern',
+          description:
+            'Always clean up useEffect hooks with return cleanup function to prevent memory leaks and stale closures.',
+        }),
+      );
+      vault.add(
+        makeEntry({
+          id: 'dup-b',
+          title: 'React hook cleanup pattern for effects',
+          description:
+            'Clean up useEffect hooks by returning a cleanup function to avoid memory leaks and stale closures.',
+        }),
+      );
+
+      // Verify they show up as duplicates
+      const before = curator.detectDuplicates();
+      const dupBefore = before.find(
+        (d) => d.entryId === 'dup-a' && d.matches.some((m) => m.entryId === 'dup-b'),
+      );
+      expect(dupBefore).toBeDefined();
+
+      // Dismiss the pair
+      const result = curator.dismissDuplicate('dup-a', 'dup-b', 'intentionally distinct');
+      expect(result.dismissed).toBe(true);
+
+      // Verify they no longer show up
+      const after = curator.detectDuplicates();
+      const dupAfter = after.find(
+        (d) => d.entryId === 'dup-a' && d.matches.some((m) => m.entryId === 'dup-b'),
+      );
+      expect(dupAfter).toBeUndefined();
+    });
+
+    it('dismissDuplicate works with swapped ID order', () => {
+      vault.add(
+        makeEntry({
+          id: 'sw-a',
+          title: 'Semantic color tokens for error states',
+          description: 'Use semantic tokens like text-error and bg-error-subtle for error UI.',
+        }),
+      );
+      vault.add(
+        makeEntry({
+          id: 'sw-b',
+          title: 'Semantic color tokens for error UI',
+          description:
+            'Always prefer semantic tokens text-error and bg-error-subtle over raw colors.',
+        }),
+      );
+
+      // Dismiss with b,a order
+      curator.dismissDuplicate('sw-b', 'sw-a');
+
+      // Should still be filtered (stored as sorted pair)
+      const results = curator.detectDuplicates('sw-a');
+      const match = results.find((r) => r.matches.some((m) => m.entryId === 'sw-b'));
+      expect(match).toBeUndefined();
+    });
+
+    it('dismissDuplicate is idempotent', () => {
+      vault.add(
+        makeEntry({
+          id: 'idem-a',
+          title: 'Pattern A idempotent test',
+          description: 'First entry for idempotency test of duplicate dismissal.',
+        }),
+      );
+      vault.add(
+        makeEntry({
+          id: 'idem-b',
+          title: 'Pattern A idempotent test duplicate',
+          description: 'Second entry for idempotency test of duplicate dismissal.',
+        }),
+      );
+
+      const first = curator.dismissDuplicate('idem-a', 'idem-b');
+      expect(first.dismissed).toBe(true);
+
+      // Second call should be a no-op (INSERT OR IGNORE)
+      const second = curator.dismissDuplicate('idem-a', 'idem-b');
+      expect(second.dismissed).toBe(false);
+    });
+  });
 });

package/src/curator/curator.ts

@@ -17,14 +17,17 @@ import type {
 } from './types.js';
 
 import {
-  detectDuplicates as detectDuplicatesPure,
   DEFAULT_DUPLICATE_THRESHOLD,
+  MERGE_SUGGESTION_THRESHOLD,
+  buildVocabulary,
+  entryToText,
 } from './duplicate-detector.js';
 import {
   findContradictions,
   DEFAULT_CONTRADICTION_THRESHOLD,
   type ContradictionCandidate,
 } from './contradiction-detector.js';
+import { tokenize, calculateTfIdf, cosineSimilarity } from '../text/similarity.js';
 import {
   normalizeTag as normalizeTagPure,
   normalizeAndDedup,
@@ -40,6 +43,7 @@ import { enrichEntryMetadata } from './metadata-enricher.js';
 // ─── Constants ──────────────────────────────────────────────────────
 
 const DEFAULT_STALE_DAYS = 90;
+const DEFAULT_BATCH_SIZE = 100;
 
 // ─── Curator Class ──────────────────────────────────────────────────
 
@@ -151,7 +155,117 @@ export class Curator {
   // ─── Duplicates (delegates to duplicate-detector) ─────────────
 
   detectDuplicates(entryId?: string, threshold?: number): DuplicateDetectionResult[] {
-    return detectDuplicatesPure(this.vault.list({ limit: 100000 }), entryId, threshold);
+    const effectiveThreshold = threshold ?? DEFAULT_DUPLICATE_THRESHOLD;
+    const dismissed = this.getDismissedPairs();
+
+    // --- Phase 1: Content-hash exact duplicates (O(n) via GROUP BY) ---
+    const exactDupes = this.provider.all<{ content_hash: string; ids: string }>(
+      `SELECT content_hash, GROUP_CONCAT(id) as ids FROM entries
+       WHERE content_hash IS NOT NULL
+       GROUP BY content_hash HAVING COUNT(*) > 1`,
+    );
+
+    const results: DuplicateDetectionResult[] = [];
+    const seenPairs = new Set<string>();
+
+    for (const { ids } of exactDupes) {
+      const idList = ids.split(',');
+      if (entryId && !idList.includes(entryId)) continue;
+      const targets = entryId ? [entryId] : idList;
+      for (const targetId of targets) {
+        const matches: DuplicateCandidate[] = [];
+        for (const otherId of idList) {
+          if (otherId === targetId) continue;
+          const pairKey = [targetId, otherId].sort().join('::');
+          if (dismissed.has(pairKey) || seenPairs.has(pairKey)) continue;
+          seenPairs.add(pairKey);
+          const other = this.vault.get(otherId);
+          if (!other) continue;
+          matches.push({
+            entryId: otherId,
+            title: other.title,
+            similarity: 1.0,
+            suggestMerge: true,
+          });
+        }
+        if (matches.length > 0) {
+          results.push({ entryId: targetId, matches, scannedCount: idList.length - 1 });
+        }
+      }
+    }
+
+    // --- Phase 2: FTS5 fuzzy candidate matching ---
+    // For each entry, use FTS5 MATCH to find top candidates, then TF-IDF cosine similarity.
+    // Complexity is O(n * k) where k = FTS5 candidate limit (10), not O(n^2).
+    const exactDupeEntryIds = new Set(results.map((r) => r.entryId));
+    const targetEntries = entryId
+      ? ([this.vault.get(entryId)].filter(Boolean) as IntelligenceEntry[])
+      : this.listBatched();
+
+    // Build vocabulary from all entries (batched)
+    const allEntries = entryId ? this.listBatched() : targetEntries;
+    const vocabulary = buildVocabulary(allEntries);
+
+    for (const entry of targetEntries) {
+      // Skip entries already fully handled by exact-hash matches
+      if (exactDupeEntryIds.has(entry.id)) continue;
+
+      // FTS5 candidate retrieval: find top-10 similar entries
+      let candidates: IntelligenceEntry[];
+      try {
+        candidates = this.vault
+          .search(entry.title, { domain: entry.domain, limit: 10 })
+          .map((r) => r.entry)
+          .filter((c) => c.id !== entry.id);
+      } catch {
+        candidates = [];
+      }
+      if (candidates.length === 0) continue;
+
+      const entryVec = calculateTfIdf(tokenize(entryToText(entry)), vocabulary);
+      const matches: DuplicateCandidate[] = [];
+
+      for (const candidate of candidates) {
+        // Skip cross-domain pairs
+        if (entry.domain !== candidate.domain) continue;
+        const pairKey = [entry.id, candidate.id].sort().join('::');
+        if (dismissed.has(pairKey)) continue;
+
+        const candidateVec = calculateTfIdf(tokenize(entryToText(candidate)), vocabulary);
+        const similarity = cosineSimilarity(entryVec, candidateVec);
+        if (similarity >= effectiveThreshold) {
+          matches.push({
+            entryId: candidate.id,
+            title: candidate.title,
+            similarity,
+            suggestMerge: similarity >= MERGE_SUGGESTION_THRESHOLD,
+          });
+        }
+      }
+
+      if (matches.length > 0) {
+        matches.sort((a, b) => b.similarity - a.similarity);
+        results.push({ entryId: entry.id, matches, scannedCount: candidates.length });
+      }
+    }
+
+    return results;
+  }
+
+  dismissDuplicate(entryIdA: string, entryIdB: string, reason?: string): { dismissed: boolean } {
+    const [a, b] = [entryIdA, entryIdB].sort();
+    const result = this.provider.run(
+      'INSERT OR IGNORE INTO curator_duplicate_dismissals (entry_id_a, entry_id_b, reason) VALUES (?, ?, ?)',
+      [a, b, reason ?? 'reviewed — not duplicate'],
+    );
+    return { dismissed: result.changes > 0 };
+  }
+
+  private getDismissedPairs(): Set<string> {
+    const rows = this.provider.all<{ entry_id_a: string; entry_id_b: string }>(
+      'SELECT entry_id_a, entry_id_b FROM curator_duplicate_dismissals',
+    );
+    return new Set(rows.map((r) => `${r.entry_id_a}::${r.entry_id_b}`));
   }
 
   // ─── Contradictions (delegates to contradiction-detector) ─────
@@ -159,9 +273,11 @@ export class Curator {
   detectContradictions(threshold?: number): Contradiction[] {
     const searchFn = (title: string) =>
       this.vault.search(title, { type: 'pattern', limit: 20 }).map((r) => r.entry);
-    return this.persistContradictions(
-      findContradictions(this.vault.list({ limit: 100000 }), threshold, searchFn),
-    );
+    // Load only anti-patterns and patterns (bounded by type), not the entire vault
+    const antipatterns = this.vault.list({ type: 'anti-pattern', limit: 10000 });
+    const patterns = this.vault.list({ type: 'pattern', limit: 10000 });
+    const entries = [...antipatterns, ...patterns];
+    return this.persistContradictions(findContradictions(entries, threshold, searchFn));
   }
 
   getContradictions(status?: ContradictionStatus): Contradiction[] {
@@ -190,10 +306,12 @@ export class Curator {
   ): Promise<{ contradictions: Contradiction[]; method: 'tfidf-only' }> {
     const searchFn = (title: string) =>
       this.vault.search(title, { type: 'pattern', limit: 20 }).map((r) => r.entry);
+    // Load only anti-patterns and patterns (bounded by type), not the entire vault
+    const antipatterns = this.vault.list({ type: 'anti-pattern', limit: 10000 });
+    const patterns = this.vault.list({ type: 'pattern', limit: 10000 });
+    const entries = [...antipatterns, ...patterns];
     return {
-      contradictions: this.persistContradictions(
-        findContradictions(this.vault.list({ limit: 100000 }), threshold, searchFn),
-      ),
+      contradictions: this.persistContradictions(findContradictions(entries, threshold, searchFn)),
       method: 'tfidf-only',
     };
   }
@@ -221,19 +339,28 @@ export class Curator {
 
   groomAll(): GroomAllResult {
     const start = Date.now();
-    const entries = this.vault.list({ limit: 100000 });
     let tagsNormalized = 0,
-      staleCount = 0;
-    for (const entry of entries) {
-      const result = this.groomEntry(entry.id);
-      if (result) {
-        tagsNormalized += result.tagsNormalized.filter((t) => t.wasAliased).length;
-        if (result.stale) staleCount++;
+      staleCount = 0,
+      totalEntries = 0;
+    // Batch pagination — process entries in batches instead of loading all at once
+    let offset = 0;
+    while (true) {
+      const batch = this.vault.list({ limit: DEFAULT_BATCH_SIZE, offset });
+      if (batch.length === 0) break;
+      totalEntries += batch.length;
+      for (const entry of batch) {
+        const result = this.groomEntry(entry.id);
+        if (result) {
+          tagsNormalized += result.tagsNormalized.filter((t) => t.wasAliased).length;
+          if (result.stale) staleCount++;
+        }
       }
+      if (batch.length < DEFAULT_BATCH_SIZE) break;
+      offset += DEFAULT_BATCH_SIZE;
     }
     return {
-      totalEntries: entries.length,
-      groomedCount: entries.length,
+      totalEntries,
+      groomedCount: totalEntries,
       tagsNormalized,
       staleCount,
       durationMs: Date.now() - start,
@@ -315,7 +442,8 @@ export class Curator {
   // ─── Health Audit (delegates to health-audit) ─────────────────
 
   healthAudit(): HealthAuditResult {
-    const entries = this.vault.list({ limit: 100000 });
+    // Load entries in batches instead of all at once
+    const entries = this.listBatched();
     const dataProvider: HealthDataProvider = {
       getStaleCount: (threshold) =>
         (
@@ -452,6 +580,22 @@ export class Curator {
 
   // ─── Private Helpers ──────────────────────────────────────────
 
+  /**
+   * Load all vault entries using batched pagination instead of a single 100k query.
+   */
+  private listBatched(batchSize: number = DEFAULT_BATCH_SIZE): IntelligenceEntry[] {
+    const all: IntelligenceEntry[] = [];
+    let offset = 0;
+    while (true) {
+      const batch = this.vault.list({ limit: batchSize, offset });
+      if (batch.length === 0) break;
+      all.push(...batch);
+      if (batch.length < batchSize) break;
+      offset += batchSize;
+    }
+    return all;
+  }
+
   private persistContradictions(candidates: ContradictionCandidate[]): Contradiction[] {
     const detected: Contradiction[] = [];
     for (const c of candidates) {

package/src/curator/schema.ts

@@ -56,6 +56,14 @@ export const CURATOR_SCHEMA = `
     resolved_at INTEGER,
     UNIQUE(pattern_id, antipattern_id)
   );
+  CREATE TABLE IF NOT EXISTS curator_duplicate_dismissals (
+    entry_id_a TEXT NOT NULL,
+    entry_id_b TEXT NOT NULL,
+    dismissed_at INTEGER NOT NULL DEFAULT (unixepoch()),
+    reason TEXT,
+    PRIMARY KEY (entry_id_a, entry_id_b)
+  );
+
   CREATE INDEX IF NOT EXISTS idx_curator_state_status ON curator_entry_state(status);
   CREATE INDEX IF NOT EXISTS idx_curator_changelog_entry ON curator_changelog(entry_id);
 `;

package/src/domain-packs/types.ts

@@ -67,12 +67,17 @@ export interface PackSkillDefinition {
 // DomainPack — the main interface
 // ---------------------------------------------------------------------------
 
+/** Pack tier: determines visibility, licensing, and install behavior */
+export type DomainPackTier = 'default' | 'community' | 'premium';
+
 /** The contract every domain pack must implement. */
 export interface DomainPack {
   /** Unique pack name (e.g., 'design', 'security-intelligence') */
   name: string;
   /** Semver version */
   version: string;
+  /** Tier: 'default' (ships with engine), 'community' (free, npm), 'premium' (unlocked today, gated later) */
+  tier?: DomainPackTier;
   /** Domains this pack claims. Ops inject into these domain facades. */
   domains: string[];
   /** Custom operations with real logic — injected into claimed domain facades. */
@@ -115,6 +120,8 @@ export interface DomainPackRef {
   package: string;
   /** Optional version constraint */
   version?: string;
+  /** Pack tier (inherited from pack if not set) */
+  tier?: DomainPackTier;
 }
 
 // ---------------------------------------------------------------------------
@@ -148,6 +155,7 @@ const packSkillSchema = z.object({
 const domainPackSchema = z.object({
   name: z.string().min(1),
   version: z.string().min(1),
+  tier: z.enum(['default', 'community', 'premium']).optional(),
   domains: z.array(z.string().min(1)).min(1),
   ops: z.array(
     z.object({

package/src/engine/module-manifest.test.ts

@@ -49,7 +49,7 @@ describe('ENGINE_MODULE_MANIFEST', () => {
       expect(entry.description.length).toBeGreaterThan(0);
       expect(Array.isArray(entry.keyOps)).toBe(true);
       expect(entry.keyOps.length).toBeGreaterThan(0);
-      expect(entry.keyOps.length).toBeLessThanOrEqual(4);
+      expect(entry.keyOps.length).toBeLessThanOrEqual(5);
     }
   });
 
@@ -69,7 +69,13 @@ describe('ENGINE_MODULE_MANIFEST', () => {
 
   it('plan module has expected keyOps', () => {
     const plan = ENGINE_MODULE_MANIFEST.find((m) => m.suffix === 'plan')!;
-    expect(plan.keyOps).toEqual(['create_plan', 'approve_plan', 'plan_split', 'plan_reconcile']);
+    expect(plan.keyOps).toEqual([
+      'create_plan',
+      'approve_plan',
+      'plan_split',
+      'plan_reconcile',
+      'plan_close_stale',
+    ]);
   });
 
   it('conditional field is optional and boolean when present', () => {

package/src/engine/module-manifest.ts

@@ -41,7 +41,7 @@ export const ENGINE_MODULE_MANIFEST: ModuleManifestEntry[] = [
   {
     suffix: 'plan',
     description: 'Plan lifecycle — create, approve, execute, reconcile, complete, grading.',
-    keyOps: ['create_plan', 'approve_plan', 'plan_split', 'plan_reconcile'],
+    keyOps: ['create_plan', 'approve_plan', 'plan_split', 'plan_reconcile', 'plan_close_stale'],
     intentSignals: {
       'plan this': 'create_plan',
       'break this down': 'create_plan',
@@ -56,7 +56,7 @@ export const ENGINE_MODULE_MANIFEST: ModuleManifestEntry[] = [
     keyOps: ['recommend', 'strengths', 'feedback'],
     intentSignals: {
       'what works': 'recommend',
-      'recommendations': 'recommend',
+      recommendations: 'recommend',
       'pattern strengths': 'strengths',
       'give feedback': 'feedback',
     },
@@ -87,7 +87,7 @@ export const ENGINE_MODULE_MANIFEST: ModuleManifestEntry[] = [
   {
     suffix: 'curator',
     description: 'Quality — duplicate detection, contradictions, grooming, health audit.',
-    keyOps: ['curator_groom', 'curator_status', 'curator_health'],
+    keyOps: ['curator_groom', 'curator_status', 'curator_health', 'curator_dismiss_duplicate'],
     intentSignals: {
       'clean up vault': 'curator_groom',
       'find duplicates': 'curator_groom',

package/src/engine/register-engine.test.ts

@@ -15,7 +15,7 @@
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { createAgentRuntime } from '../runtime/runtime.js';
-import { registerEngine, ENGINE_MODULES } from './register-engine.js';
+import { registerEngine, ENGINE_MODULES, INTERNAL_OPS } from './register-engine.js';
 import { ENGINE_MODULE_MANIFEST } from './module-manifest.js';
 import type { AgentRuntime } from '../runtime/types.js';
 import type { OpDefinition } from '../facades/types.js';
@@ -233,3 +233,75 @@ describe('ENGINE_MODULES descriptions match manifest', () => {
     }
   });
 });
+
+describe('registerEngine — op visibility', () => {
+  it('INTERNAL_OPS set contains expected ops', () => {
+    // Spot-check known internal ops
+    expect(INTERNAL_OPS.has('admin_create_token')).toBe(true);
+    expect(INTERNAL_OPS.has('vault_bulk_add')).toBe(true);
+    expect(INTERNAL_OPS.has('plan_auto_reconcile')).toBe(true);
+    expect(INTERNAL_OPS.has('telemetry_errors')).toBe(true);
+    // User-facing ops should NOT be in the set
+    expect(INTERNAL_OPS.has('admin_health')).toBe(false);
+    expect(INTERNAL_OPS.has('search_intelligent')).toBe(false);
+    expect(INTERNAL_OPS.has('create_plan')).toBe(false);
+  });
+
+  it('INTERNAL_OPS has at least 25 entries', () => {
+    expect(INTERNAL_OPS.size).toBeGreaterThanOrEqual(25);
+  });
+
+  it('ops without visibility field default to user (backward compat)', () => {
+    const server = makeServer();
+    const userOp: OpDefinition = {
+      name: 'my_visible_op',
+      description: 'Visible op',
+      auth: 'read',
+      handler: async () => 'ok',
+    };
+    const result = registerEngine(server, runtime, {
+      agentId: 'vis',
+      domainPacks: [{ name: 'test', facades: [{ name: 'test', ops: [userOp] }] }],
+    });
+    expect(result.tools).toContain('vis_test');
+  });
+
+  it('ops with visibility: internal are excluded from MCP tool description but remain callable', () => {
+    const server = makeServer();
+    const visibleOp: OpDefinition = {
+      name: 'public_op',
+      description: 'Public op',
+      auth: 'read',
+      handler: async () => 'visible',
+    };
+    const internalOp: OpDefinition = {
+      name: 'secret_op',
+      description: 'Internal op',
+      auth: 'admin',
+      visibility: 'internal',
+      handler: async () => 'hidden',
+    };
+    // Register both ops under a pack facade
+    registerEngine(server, runtime, {
+      agentId: 'vt',
+      domainPacks: [{ name: 'test', facades: [{ name: 'check', ops: [visibleOp, internalOp] }] }],
+    });
+    // We can't easily inspect the MCP schema description string, but we verify
+    // that registration succeeds with mixed visibility ops
+    expect(true).toBe(true);
+  });
+
+  it('every INTERNAL_OPS entry corresponds to a real op in some facade', () => {
+    // Collect all op names across all engine modules
+    const allOpNames = new Set<string>();
+    for (const mod of ENGINE_MODULES) {
+      const ops = mod.createOps(runtime);
+      for (const op of ops) {
+        allOpNames.add(op.name);
+      }
+    }
+    for (const internalOp of INTERNAL_OPS) {
+      expect(allOpNames.has(internalOp)).toBe(true);
+    }
+  });
+});

package/src/engine/register-engine.ts

@@ -295,11 +295,70 @@ export function registerEngine(
   return { tools: registeredTools, totalOps, registerTool };
 }
 
+// ─── Op Visibility ───────────────────────────────────────────────────
+
+/**
+ * Ops classified as internal — hidden from MCP tool descriptions but still
+ * callable programmatically. Centralized here for easy auditing.
+ *
+ * Criteria: ops that are infrastructure plumbing, token/account management,
+ * bulk operations, or auto-* automation that users never call directly.
+ */
+/** @internal Exported for testing — do not use outside engine */
+export const INTERNAL_OPS = new Set([
+  // Admin: token management
+  'admin_create_token',
+  'admin_revoke_token',
+  'admin_list_tokens',
+  // Admin: account management
+  'admin_add_account',
+  'admin_remove_account',
+  'admin_rotate_account',
+  'admin_list_accounts',
+  'admin_account_status',
+  // Admin: infrastructure debug
+  'admin_vault_size',
+  'admin_vault_analytics',
+  'admin_search_insights',
+  'admin_env',
+  'admin_gc',
+  'admin_export_config',
+  'admin_key_pool_status',
+  'admin_persistence_info',
+  // Admin: flags
+  'admin_list_flags',
+  'admin_get_flag',
+  'admin_set_flag',
+  // Admin: setup internals
+  'admin_inject_claude_md',
+  // Admin: telemetry
+  'admin_telemetry',
+  'admin_telemetry_recent',
+  'admin_telemetry_reset',
+  'telemetry_errors',
+  'telemetry_slow_ops',
+  // Vault: bulk operations
+  'vault_bulk_add',
+  'vault_bulk_remove',
+  // Plan: automation
+  'plan_auto_reconcile',
+  'plan_auto_improve',
+]);
+
+/** Resolve effective visibility: explicit field wins, then INTERNAL_OPS set, else 'user'. */
+function resolveVisibility(op: OpDefinition): 'user' | 'internal' {
+  if (op.visibility) return op.visibility;
+  return INTERNAL_OPS.has(op.name) ? 'internal' : 'user';
+}
+
 // ─── Tool Registration (No Factory) ──────────────────────────────────
 
 /**
  * Register a single grouped tool with op dispatch.
  * This is the replacement for registerFacade() — same behavior, no FacadeConfig type.
+ *
+ * Internal ops (visibility: 'internal') are excluded from the MCP tool description
+ * but remain dispatchable — they just don't show up in the op list Claude sees.
  */
 function registerModuleTool(
   server: McpServer,
@@ -308,7 +367,8 @@ function registerModuleTool(
   ops: OpDefinition[],
   authPolicy?: () => AuthPolicy,
 ): void {
-  const opNames = ops.map((o) => o.name);
+  const userOps = ops.filter((o) => resolveVisibility(o) !== 'internal');
+  const opNames = userOps.map((o) => o.name);
   const opMap = new Map(ops.map((o) => [o.name, o]));
 
   server.tool(

package/src/facades/types.ts

@@ -25,6 +25,9 @@ export const AUTH_LEVEL_RANK: Record<AuthLevel, number> = {
   admin: 2,
 };
 
+/** Op visibility — controls whether an op is exposed via MCP tool registration */
+export type OpVisibility = 'user' | 'internal';
+
 /** Operation definition within a facade */
 export interface OpDefinition {
   name: string;
@@ -34,6 +37,8 @@ export interface OpDefinition {
   schema?: z.ZodType;
   /** Promote to a first-class MCP tool with full schema discovery. */
   hot?: boolean;
+  /** Controls MCP exposure: 'user' (default) = listed in tool, 'internal' = hidden from MCP but callable programmatically. */
+  visibility?: OpVisibility;
 }
 
 /** Facade configuration — one MCP tool */