@soleri/core 2.10.0 → 2.11.0

package/src/enforcement/adapters/claude-code.ts

@@ -0,0 +1,135 @@
+/**
+ * Claude Code host adapter — translates enforcement rules to Claude Code hooks.
+ *
+ * Maps:
+ * - pre-tool-use → PreToolUse hooks in settings.json
+ * - pre-commit → UserPromptSubmit hook checking git commit
+ * - pre-compact → PreCompact hook
+ * - session-start → SessionStart hook
+ */
+
+import type {
+  EnforcementConfig,
+  EnforcementTrigger,
+  HostAdapter,
+  HostAdapterResult,
+} from '../types.js';
+
+const TRIGGER_TO_EVENT: Partial<Record<EnforcementTrigger, string>> = {
+  'pre-tool-use': 'PreToolUse',
+  'post-tool-use': 'PostToolUse',
+  'pre-compact': 'PreCompact',
+  'session-start': 'SessionStart',
+};
+
+export class ClaudeCodeAdapter implements HostAdapter {
+  readonly host = 'claude-code';
+
+  supports(trigger: EnforcementTrigger): boolean {
+    return trigger in TRIGGER_TO_EVENT || trigger === 'pre-commit';
+  }
+
+  translate(config: EnforcementConfig): HostAdapterResult {
+    const hooks: Array<{ event: string; command: string; ruleId: string }> = [];
+    const hookFiles: Array<{ path: string; content: string; ruleId: string }> = [];
+    const skipped: Array<{ ruleId: string; reason: string }> = [];
+
+    for (const rule of config.rules) {
+      if (!this.supports(rule.trigger)) {
+        skipped.push({ ruleId: rule.id, reason: `Trigger '${rule.trigger}' not supported` });
+        continue;
+      }
+
+      if (rule.trigger === 'pre-commit') {
+        // Pre-commit uses a hookify-style .local.md file
+        hookFiles.push({
+          path: `.claude/hookify.${rule.id}.local.md`,
+          content: this.generateHookFile(rule.id, rule.description, rule.pattern, rule.message),
+          ruleId: rule.id,
+        });
+        continue;
+      }
+
+      const event = TRIGGER_TO_EVENT[rule.trigger];
+      if (!event) {
+        skipped.push({ ruleId: rule.id, reason: `No event mapping for '${rule.trigger}'` });
+        continue;
+      }
+
+      if (rule.pattern) {
+        // Pattern-based hook
+        hooks.push({
+          event,
+          command: this.generatePatternCommand(rule.id, rule.pattern, rule.action, rule.message),
+          ruleId: rule.id,
+        });
+      } else {
+        // Simple event hook
+        hooks.push({
+          event,
+          command: `echo "[${rule.id}] ${rule.message}"`,
+          ruleId: rule.id,
+        });
+      }
+    }
+
+    const files: Array<{ path: string; content: string }> = [];
+
+    // Generate settings.json hooks section
+    if (hooks.length > 0) {
+      const settingsHooks = hooks.map((h) => ({
+        event: h.event,
+        command: h.command,
+      }));
+      files.push({
+        path: '.claude/settings.json',
+        content: JSON.stringify({ hooks: settingsHooks }, null, 2),
+      });
+    }
+
+    // Add hookify files
+    for (const hf of hookFiles) {
+      files.push({ path: hf.path, content: hf.content });
+    }
+
+    return { host: this.host, files, skipped };
+  }
+
+  private generatePatternCommand(
+    ruleId: string,
+    pattern: string,
+    action: string,
+    message: string,
+  ): string {
+    if (action === 'block') {
+      return `grep -rn '${pattern}' "$TOOL_INPUT" 2>/dev/null && echo "BLOCKED [${ruleId}]: ${message}" && exit 1 || exit 0`;
+    }
+    return `grep -rn '${pattern}' "$TOOL_INPUT" 2>/dev/null && echo "WARNING [${ruleId}]: ${message}" || true`;
+  }
+
+  private generateHookFile(
+    id: string,
+    description: string,
+    pattern?: string,
+    message?: string,
+  ): string {
+    const lines = [
+      '---',
+      `name: ${id}`,
+      `description: ${description}`,
+      '---',
+      '',
+      `# ${id}`,
+      '',
+      description,
+      '',
+    ];
+    if (pattern) {
+      lines.push(`Pattern: \`${pattern}\``);
+    }
+    if (message) {
+      lines.push('', message);
+    }
+    return lines.join('\n');
+  }
+}

package/src/enforcement/adapters/index.ts

@@ -0,0 +1 @@
+export { ClaudeCodeAdapter } from './claude-code.js';

package/src/enforcement/index.ts

@@ -0,0 +1,10 @@
+export { EnforcementRegistry } from './registry.js';
+export { ClaudeCodeAdapter } from './adapters/index.js';
+export type {
+  EnforcementTrigger,
+  EnforcementAction,
+  EnforcementRule,
+  EnforcementConfig,
+  HostAdapterResult,
+  HostAdapter,
+} from './types.js';

package/src/enforcement/registry.ts

@@ -0,0 +1,82 @@
+/**
+ * Enforcement registry — manages rules and adapters.
+ */
+
+import type {
+  EnforcementConfig,
+  EnforcementRule,
+  HostAdapter,
+  HostAdapterResult,
+} from './types.js';
+
+export class EnforcementRegistry {
+  private rules: EnforcementRule[] = [];
+  private adapters = new Map<string, HostAdapter>();
+
+  addRule(rule: EnforcementRule): void {
+    // Replace if same ID exists
+    this.rules = this.rules.filter((r) => r.id !== rule.id);
+    this.rules.push(rule);
+  }
+
+  addRules(rules: EnforcementRule[]): void {
+    for (const rule of rules) {
+      this.addRule(rule);
+    }
+  }
+
+  removeRule(id: string): boolean {
+    const before = this.rules.length;
+    this.rules = this.rules.filter((r) => r.id !== id);
+    return this.rules.length < before;
+  }
+
+  getRule(id: string): EnforcementRule | undefined {
+    return this.rules.find((r) => r.id === id);
+  }
+
+  getRules(): EnforcementRule[] {
+    return [...this.rules];
+  }
+
+  getEnabledRules(): EnforcementRule[] {
+    return this.rules.filter((r) => r.enabled !== false);
+  }
+
+  getConfig(): EnforcementConfig {
+    return { rules: this.getEnabledRules() };
+  }
+
+  registerAdapter(adapter: HostAdapter): void {
+    this.adapters.set(adapter.host, adapter);
+  }
+
+  getAdapter(host: string): HostAdapter | undefined {
+    return this.adapters.get(host);
+  }
+
+  listAdapters(): string[] {
+    return [...this.adapters.keys()];
+  }
+
+  /** Translate rules for a specific host */
+  translate(host: string): HostAdapterResult {
+    const adapter = this.adapters.get(host);
+    if (!adapter) {
+      return {
+        host,
+        files: [],
+        skipped: this.getEnabledRules().map((r) => ({
+          ruleId: r.id,
+          reason: `No adapter registered for host: ${host}`,
+        })),
+      };
+    }
+    return adapter.translate(this.getConfig());
+  }
+
+  /** Translate rules for all registered adapters */
+  translateAll(): HostAdapterResult[] {
+    return [...this.adapters.keys()].map((host) => this.translate(host));
+  }
+}

package/src/enforcement/types.ts

@@ -0,0 +1,56 @@
+/**
+ * Host-agnostic enforcement declarations.
+ *
+ * Agents declare rules abstractly; host adapters translate
+ * to platform-specific enforcement (Claude Code hooks, Cursor rules, etc.)
+ */
+
+/** When the rule should trigger */
+export type EnforcementTrigger =
+  | 'pre-tool-use' // Before a tool executes (e.g., PreToolUse hook)
+  | 'post-tool-use' // After a tool executes
+  | 'pre-commit' // Before git commit
+  | 'pre-compact' // Before context compaction
+  | 'session-start' // On session initialization
+  | 'on-save'; // On file save
+
+/** What happens when a rule matches */
+export type EnforcementAction = 'block' | 'warn' | 'suggest';
+
+/** A single enforcement rule declared by the agent */
+export interface EnforcementRule {
+  id: string;
+  description: string;
+  trigger: EnforcementTrigger;
+  /** Regex pattern to match (in file content, tool args, etc.) */
+  pattern?: string;
+  /** Context filter — only applies when this context is active */
+  context?: string;
+  /** What to do on match */
+  action: EnforcementAction;
+  /** Message shown to user/LLM when triggered */
+  message: string;
+  /** Whether this rule is enabled (default: true) */
+  enabled?: boolean;
+}
+
+/** Complete enforcement config for an agent */
+export interface EnforcementConfig {
+  rules: EnforcementRule[];
+}
+
+/** Result of translating rules for a specific host */
+export interface HostAdapterResult {
+  host: string;
+  files: Array<{ path: string; content: string }>;
+  skipped: Array<{ ruleId: string; reason: string }>;
+}
+
+/** Host adapter interface — translates abstract rules to host-specific config */
+export interface HostAdapter {
+  readonly host: string;
+  /** Check if this adapter supports a given trigger type */
+  supports(trigger: EnforcementTrigger): boolean;
+  /** Translate rules to host-specific config files */
+  translate(config: EnforcementConfig): HostAdapterResult;
+}

package/src/facades/facade-factory.ts

@@ -1,8 +1,13 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import type { FacadeConfig, FacadeResponse } from './types.js';
+import type { FacadeConfig, FacadeResponse, AuthPolicy, OpDefinition } from './types.js';
+import { AUTH_LEVEL_RANK } from './types.js';
 
-export function registerFacade(server: McpServer, facade: FacadeConfig): void {
+export function registerFacade(
+  server: McpServer,
+  facade: FacadeConfig,
+  authPolicy?: () => AuthPolicy,
+): void {
   const opNames = facade.ops.map((o) => o.name);
 
   server.tool(
@@ -13,16 +18,47 @@ export function registerFacade(server: McpServer, facade: FacadeConfig): void {
       params: z.record(z.unknown()).optional().default({}).describe('Operation parameters'),
     },
     async ({ op, params }): Promise<{ content: Array<{ type: 'text'; text: string }> }> => {
-      const response = await dispatchOp(facade, op, params);
+      const response = await dispatchOp(facade, op, params, authPolicy?.());
       return { content: [{ type: 'text' as const, text: JSON.stringify(response, null, 2) }] };
     },
   );
 }
 
+function checkAuth(
+  opName: string,
+  opAuth: string,
+  facadeName: string,
+  policy: AuthPolicy | undefined,
+): FacadeResponse | null {
+  if (!policy || policy.mode === 'permissive') return null;
+
+  const requiredLevel = policy.overrides?.[opName] ?? (opAuth as keyof typeof AUTH_LEVEL_RANK);
+  const callerRank = AUTH_LEVEL_RANK[policy.callerLevel] ?? 0;
+  const requiredRank = AUTH_LEVEL_RANK[requiredLevel as keyof typeof AUTH_LEVEL_RANK] ?? 0;
+
+  if (callerRank >= requiredRank) return null;
+
+  const message = `Auth denied: "${opName}" requires ${requiredLevel}, caller has ${policy.callerLevel}`;
+
+  if (policy.mode === 'warn') {
+    console.error(`[auth-warn] ${message}`);
+    return null; // warn but allow
+  }
+
+  // enforce mode — block
+  return {
+    success: false,
+    error: message,
+    op: opName,
+    facade: facadeName,
+  };
+}
+
 async function dispatchOp(
   facade: FacadeConfig,
   opName: string,
   params: Record<string, unknown>,
+  authPolicy?: AuthPolicy,
 ): Promise<FacadeResponse> {
   const op = facade.ops.find((o) => o.name === opName);
   if (!op) {
@@ -34,6 +70,10 @@ async function dispatchOp(
     };
   }
 
+  // Auth check — before validation or execution
+  const authResult = checkAuth(opName, op.auth, facade.name, authPolicy);
+  if (authResult) return authResult;
+
   try {
     let validatedParams = params;
     if (op.schema) {
@@ -57,8 +97,101 @@ async function dispatchOp(
   }
 }
 
-export function registerAllFacades(server: McpServer, facades: FacadeConfig[]): void {
+/**
+ * Register a single hot op as a standalone MCP tool with full schema discovery.
+ * The op remains in its facade too — this is additive, not a move.
+ */
+function registerHotOp(
+  server: McpServer,
+  agentId: string,
+  facadeName: string,
+  op: OpDefinition,
+  authPolicy?: () => AuthPolicy,
+): void {
+  const toolName = `${agentId}_${op.name}`;
+  const schema = op.schema
+    ? (op.schema as z.ZodObject<z.ZodRawShape>).shape
+      ? (op.schema as z.ZodObject<z.ZodRawShape>)
+      : z.object({ params: op.schema })
+    : z.object({});
+
+  server.tool(
+    toolName,
+    op.description,
+    schema instanceof z.ZodObject ? schema.shape : {},
+    async (params): Promise<{ content: Array<{ type: 'text'; text: string }> }> => {
+      const policy = authPolicy?.();
+      const authResult = checkAuth(op.name, op.auth, facadeName, policy);
+      if (authResult) {
+        return { content: [{ type: 'text' as const, text: JSON.stringify(authResult, null, 2) }] };
+      }
+
+      try {
+        let validatedParams = params as Record<string, unknown>;
+        if (op.schema) {
+          const result = op.schema.safeParse(params);
+          if (!result.success) {
+            const response: FacadeResponse = {
+              success: false,
+              error: `Invalid params: ${result.error.message}`,
+              op: op.name,
+              facade: facadeName,
+            };
+            return {
+              content: [{ type: 'text' as const, text: JSON.stringify(response, null, 2) }],
+            };
+          }
+          validatedParams = result.data as Record<string, unknown>;
+        }
+
+        const data = await op.handler(validatedParams);
+        const response: FacadeResponse = { success: true, data, op: op.name, facade: facadeName };
+        return { content: [{ type: 'text' as const, text: JSON.stringify(response, null, 2) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const response: FacadeResponse = {
+          success: false,
+          error: message,
+          op: op.name,
+          facade: facadeName,
+        };
+        return { content: [{ type: 'text' as const, text: JSON.stringify(response, null, 2) }] };
+      }
+    },
+  );
+}
+
+export interface RegisterOptions {
+  authPolicy?: () => AuthPolicy;
+  /** Agent ID prefix for hot op tool names */
+  agentId?: string;
+  /** Op names to promote to standalone MCP tools (requires agentId) */
+  hotOps?: Set<string> | string[];
+}
+
+export function registerAllFacades(
+  server: McpServer,
+  facades: FacadeConfig[],
+  authPolicyOrOptions?: (() => AuthPolicy) | RegisterOptions,
+): void {
+  // Support both legacy signature and new options
+  const opts: RegisterOptions =
+    typeof authPolicyOrOptions === 'function'
+      ? { authPolicy: authPolicyOrOptions }
+      : (authPolicyOrOptions ?? {});
+
+  const hotSet = opts.hotOps instanceof Set ? opts.hotOps : new Set(opts.hotOps ?? []);
+
   for (const facade of facades) {
-    registerFacade(server, facade);
+    registerFacade(server, facade, opts.authPolicy);
+
+    // Promote hot ops to standalone tools
+    if (opts.agentId) {
+      for (const op of facade.ops) {
+        if (op.hot || hotSet.has(op.name)) {
+          registerHotOp(server, opts.agentId, facade.name, op, opts.authPolicy);
+        }
+      }
+    }
   }
 }

package/src/facades/types.ts

@@ -6,6 +6,25 @@ export type OpHandler = (params: Record<string, unknown>) => Promise<unknown>;
 /** Auth level required for an operation */
 export type AuthLevel = 'read' | 'write' | 'admin';
 
+/** Auth enforcement mode */
+export type AuthMode = 'permissive' | 'warn' | 'enforce';
+
+/** Auth policy for facade dispatch */
+export interface AuthPolicy {
+  mode: AuthMode;
+  /** Caller's auth level — ops requiring a higher level are blocked/warned */
+  callerLevel: AuthLevel;
+  /** Per-op overrides: opName → required level */
+  overrides?: Record<string, AuthLevel>;
+}
+
+/** Numeric auth level for comparison: read=0, write=1, admin=2 */
+export const AUTH_LEVEL_RANK: Record<AuthLevel, number> = {
+  read: 0,
+  write: 1,
+  admin: 2,
+};
+
 /** Operation definition within a facade */
 export interface OpDefinition {
   name: string;
@@ -13,6 +32,8 @@ export interface OpDefinition {
   auth: AuthLevel;
   handler: OpHandler;
   schema?: z.ZodType;
+  /** Promote to a first-class MCP tool with full schema discovery. */
+  hot?: boolean;
 }
 
 /** Facade configuration — one MCP tool */

package/src/health/health-registry.ts

@@ -0,0 +1,165 @@
+/**
+ * Centralized health registry — subsystems report status,
+ * consumers observe transitions, self-healing retries on recovery.
+ */
+
+export type SubsystemStatus = 'healthy' | 'degraded' | 'down';
+
+export interface SubsystemHealth {
+  name: string;
+  status: SubsystemStatus;
+  lastCheckedAt: number;
+  lastHealthyAt: number | null;
+  failureCount: number;
+  lastError: string | null;
+}
+
+export type StatusChangeListener = (
+  name: string,
+  prev: SubsystemStatus,
+  next: SubsystemStatus,
+) => void;
+
+export type RecoveryHook = (name: string) => void | Promise<void>;
+
+export interface HealthSnapshot {
+  overall: SubsystemStatus;
+  subsystems: Record<string, SubsystemHealth>;
+  registeredAt: number;
+}
+
+export class HealthRegistry {
+  private subsystems = new Map<string, SubsystemHealth>();
+  private listeners: StatusChangeListener[] = [];
+  private recoveryHooks = new Map<string, RecoveryHook[]>();
+  private readonly registeredAt = Date.now();
+
+  register(name: string, initialStatus: SubsystemStatus = 'healthy'): void {
+    if (this.subsystems.has(name)) return;
+    this.subsystems.set(name, {
+      name,
+      status: initialStatus,
+      lastCheckedAt: Date.now(),
+      lastHealthyAt: initialStatus === 'healthy' ? Date.now() : null,
+      failureCount: 0,
+      lastError: null,
+    });
+  }
+
+  update(name: string, status: SubsystemStatus, error?: string): void {
+    let sub = this.subsystems.get(name);
+    if (!sub) {
+      this.register(name, status);
+      sub = this.subsystems.get(name)!;
+      if (error) sub.lastError = error;
+      return;
+    }
+
+    const prev = sub.status;
+    sub.status = status;
+    sub.lastCheckedAt = Date.now();
+
+    if (status === 'healthy') {
+      sub.lastHealthyAt = Date.now();
+      sub.failureCount = 0;
+      sub.lastError = null;
+    } else {
+      sub.failureCount++;
+      if (error) sub.lastError = error;
+    }
+
+    if (prev !== status) {
+      for (const listener of this.listeners) {
+        try {
+          listener(name, prev, status);
+        } catch {
+          // Listener errors must not crash the registry
+        }
+      }
+
+      // Trigger recovery hooks when transitioning TO healthy
+      if (status === 'healthy' && prev !== 'healthy') {
+        this.triggerRecovery(name);
+      }
+    }
+  }
+
+  get(name: string): SubsystemHealth | undefined {
+    return this.subsystems.get(name);
+  }
+
+  snapshot(): HealthSnapshot {
+    const subsystems: Record<string, SubsystemHealth> = {};
+    for (const [name, health] of this.subsystems) {
+      subsystems[name] = { ...health };
+    }
+    return {
+      overall: this.computeOverall(),
+      subsystems,
+      registeredAt: this.registeredAt,
+    };
+  }
+
+  onStatusChange(listener: StatusChangeListener): void {
+    this.listeners.push(listener);
+  }
+
+  onRecovery(subsystem: string, hook: RecoveryHook): void {
+    const hooks = this.recoveryHooks.get(subsystem) ?? [];
+    hooks.push(hook);
+    this.recoveryHooks.set(subsystem, hooks);
+  }
+
+  private triggerRecovery(name: string): void {
+    const hooks = this.recoveryHooks.get(name);
+    if (!hooks) return;
+    for (const hook of hooks) {
+      try {
+        const result = hook(name);
+        if (result instanceof Promise) {
+          result.catch(() => {
+            // Recovery hook failure is non-fatal
+          });
+        }
+      } catch {
+        // Recovery hook failure is non-fatal
+      }
+    }
+  }
+
+  private computeOverall(): SubsystemStatus {
+    let hasDown = false;
+    let hasDegraded = false;
+    for (const sub of this.subsystems.values()) {
+      if (sub.status === 'down') hasDown = true;
+      if (sub.status === 'degraded') hasDegraded = true;
+    }
+    if (hasDown) return 'down';
+    if (hasDegraded) return 'degraded';
+    return 'healthy';
+  }
+}
+
+/**
+ * Wrap an async call with graceful degradation.
+ * On failure, returns the fallback value and updates health registry.
+ */
+export async function withDegradation<T>(
+  registry: HealthRegistry,
+  subsystem: string,
+  fn: () => Promise<T>,
+  fallback: T,
+): Promise<T> {
+  try {
+    const result = await fn();
+    registry.update(subsystem, 'healthy');
+    return result;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const current = registry.get(subsystem);
+    // First failure = degraded, repeated = down
+    const status: SubsystemStatus = current && current.status === 'degraded' ? 'down' : 'degraded';
+    registry.update(subsystem, status, message);
+    return fallback;
+  }
+}

package/src/health/index.ts

@@ -0,0 +1,11 @@
+export { HealthRegistry, withDegradation } from './health-registry.js';
+export type {
+  SubsystemStatus,
+  SubsystemHealth,
+  StatusChangeListener,
+  RecoveryHook,
+  HealthSnapshot,
+} from './health-registry.js';
+
+export { checkVaultIntegrity } from './vault-integrity.js';
+export type { IntegrityResult } from './vault-integrity.js';