@soleri/core 2.0.2 → 2.4.0

package/src/governance/types.ts

@@ -0,0 +1,111 @@
+// ─── Policy Types ───────────────────────────────────────────────────
+
+export type PolicyType = 'quota' | 'retention' | 'auto-capture';
+export type PolicyPreset = 'strict' | 'moderate' | 'permissive';
+export type PolicyAction = 'capture' | 'quarantine' | 'reject' | 'propose';
+
+export interface QuotaPolicy {
+  maxEntriesTotal: number;
+  maxEntriesPerCategory: number;
+  maxEntriesPerType: number;
+  warnAtPercent: number;
+}
+
+export interface RetentionPolicy {
+  archiveAfterDays: number;
+  minHitsToKeep: number;
+  deleteArchivedAfterDays: number;
+}
+
+export interface AutoCapturePolicy {
+  enabled: boolean;
+  requireReview: boolean;
+  maxPendingProposals: number;
+  autoExpireDays: number;
+}
+
+export interface VaultPolicy {
+  projectPath: string;
+  quotas: QuotaPolicy;
+  retention: RetentionPolicy;
+  autoCapture: AutoCapturePolicy;
+}
+
+export interface QuotaStatus {
+  total: number;
+  maxTotal: number;
+  byCategory: Record<string, number>;
+  byType: Record<string, number>;
+  warnAtPercent: number;
+  isWarning: boolean;
+}
+
+export interface PolicyDecision {
+  allowed: boolean;
+  action: PolicyAction;
+  reason?: string;
+  quotaStatus?: QuotaStatus;
+}
+
+export interface BatchDecision {
+  entry: { type: string; category: string; title?: string };
+  decision: PolicyDecision;
+}
+
+export interface PolicyAuditEntry {
+  id: number;
+  projectPath: string;
+  policyType: string;
+  oldConfig: Record<string, unknown> | null;
+  newConfig: Record<string, unknown>;
+  changedBy: string | null;
+  changedAt: number;
+}
+
+// ─── Proposal Types ─────────────────────────────────────────────────
+
+export type ProposalStatus = 'pending' | 'approved' | 'rejected' | 'modified' | 'expired';
+
+export interface Proposal {
+  id: number;
+  projectPath: string;
+  entryId: string | null;
+  title: string;
+  type: string;
+  category: string;
+  proposedData: Record<string, unknown>;
+  status: ProposalStatus;
+  proposedAt: number;
+  decidedAt: number | null;
+  decidedBy: string | null;
+  modificationNote: string | null;
+  source: string;
+}
+
+export interface ProposalStats {
+  total: number;
+  pending: number;
+  approved: number;
+  rejected: number;
+  modified: number;
+  expired: number;
+  acceptanceRate: number;
+  byCategory: Record<string, { total: number; accepted: number; rate: number }>;
+}
+
+// ─── Dashboard ──────────────────────────────────────────────────────
+
+export interface GovernanceDashboard {
+  vaultSize: number;
+  quotaPercent: number;
+  quotaStatus: QuotaStatus;
+  pendingProposals: number;
+  acceptanceRate: number;
+  evaluationTrend: Record<string, number>;
+  policySummary: {
+    maxEntries: number;
+    requireReview: boolean;
+    archiveAfterDays: number;
+    autoExpireDays: number;
+  };
+}

package/src/index.ts

@@ -37,8 +37,29 @@ export type {
   CuratorStatus,
 } from './curator/types.js';
 
+// ─── Governance ─────────────────────────────────────────────────────
+export { Governance } from './governance/governance.js';
+export type {
+  PolicyType,
+  PolicyPreset,
+  PolicyAction,
+  QuotaPolicy,
+  RetentionPolicy,
+  AutoCapturePolicy,
+  VaultPolicy,
+  QuotaStatus,
+  PolicyDecision,
+  BatchDecision,
+  PolicyAuditEntry,
+  ProposalStatus,
+  Proposal,
+  ProposalStats,
+  GovernanceDashboard,
+} from './governance/types.js';
+
 // ─── Brain ───────────────────────────────────────────────────────────
 export { Brain } from './brain/brain.js';
+export { BrainIntelligence } from './brain/intelligence.js';
 export type {
   ScoringWeights,
   ScoreBreakdown,
@@ -47,11 +68,74 @@ export type {
   CaptureResult,
   BrainStats,
   QueryContext,
-} from './brain/brain.js';
+  FeedbackType,
+  FeedbackSource,
+  FeedbackInput,
+  FeedbackEntry,
+  FeedbackStats,
+  PatternStrength,
+  StrengthsQuery,
+  BrainSession,
+  SessionLifecycleInput,
+  KnowledgeProposal,
+  ExtractionResult,
+  GlobalPattern,
+  DomainProfile,
+  BuildIntelligenceResult,
+  BrainIntelligenceStats,
+  SessionContext,
+  BrainExportData,
+  BrainImportResult,
+} from './brain/types.js';
+
+// ─── Cognee ─────────────────────────────────────────────────────────
+export { CogneeClient } from './cognee/client.js';
+export type {
+  CogneeConfig,
+  CogneeSearchResult,
+  CogneeSearchType,
+  CogneeStatus,
+  CogneeAddResult,
+  CogneeCognifyResult,
+} from './cognee/types.js';
 
 // ─── Planning ────────────────────────────────────────────────────────
-export { Planner } from './planning/planner.js';
-export type { PlanStatus, TaskStatus, PlanTask, Plan, PlanStore } from './planning/planner.js';
+export { Planner, calculateScore } from './planning/planner.js';
+export type {
+  PlanStatus,
+  TaskStatus,
+  PlanTask,
+  Plan,
+  PlanStore,
+  DriftItem,
+  ReconciliationReport,
+  ReviewEvidence,
+  PlanGrade,
+  PlanCheck,
+} from './planning/planner.js';
+
+// ─── Plan Gap Analysis ──────────────────────────────────────────────
+export { runGapAnalysis } from './planning/gap-analysis.js';
+export type { GapAnalysisOptions, GapAnalysisPass } from './planning/gap-analysis.js';
+export {
+  SEVERITY_WEIGHTS,
+  CATEGORY_PENALTY_CAPS,
+  MIN_OBJECTIVE_LENGTH,
+  MIN_SCOPE_LENGTH,
+  MIN_DECISION_LENGTH,
+  generateGapId,
+} from './planning/gap-types.js';
+export type { GapSeverity, GapCategory, PlanGap } from './planning/gap-types.js';
+
+// ─── Loop ────────────────────────────────────────────────────────────
+export { LoopManager } from './loop/loop-manager.js';
+export type {
+  LoopMode,
+  LoopConfig,
+  LoopIteration,
+  LoopStatus,
+  LoopState,
+} from './loop/types.js';
 
 // ─── LLM Types ───────────────────────────────────────────────────────
 export { SecretString, LLMError } from './llm/types.js';
@@ -97,8 +181,49 @@ export type {
 // ─── LLM Client ─────────────────────────────────────────────────────
 export { LLMClient } from './llm/llm-client.js';
 
+// ─── Control ────────────────────────────────────────────────────────
+export { IdentityManager } from './control/identity-manager.js';
+export { IntentRouter } from './control/intent-router.js';
+export type {
+  GuidelineCategory,
+  Guideline,
+  AgentIdentity,
+  IdentityVersion,
+  IdentityUpdateInput,
+  GuidelineInput,
+  IntentType,
+  OperationalMode,
+  IntentClassification,
+  ModeConfig,
+  MorphResult,
+} from './control/types.js';
+
+// ─── Project Registry ──────────────────────────────────────────────
+export { ProjectRegistry } from './project/project-registry.js';
+export type { RegisteredProject, ProjectRule, LinkType, ProjectLink } from './project/types.js';
+
+// ─── Telemetry ─────────────────────────────────────────────────────
+export { Telemetry } from './telemetry/telemetry.js';
+export type { FacadeCall, TelemetryStats } from './telemetry/telemetry.js';
+
+// ─── Logging ────────────────────────────────────────────────────────
+export { Logger, createLogger } from './logging/logger.js';
+export type { LogLevel, LogEntry, LogContext, LoggerConfig } from './logging/types.js';
+
 // ─── Runtime Factory ────────────────────────────────────────────────
 export { createAgentRuntime } from './runtime/runtime.js';
 export { createCoreOps } from './runtime/core-ops.js';
 export { createDomainFacade, createDomainFacades } from './runtime/domain-ops.js';
+export { createPlanningExtraOps } from './runtime/planning-extra-ops.js';
+export { createMemoryExtraOps } from './runtime/memory-extra-ops.js';
+export { createVaultExtraOps } from './runtime/vault-extra-ops.js';
+export { createAdminOps } from './runtime/admin-ops.js';
+export { createAdminExtraOps } from './runtime/admin-extra-ops.js';
+export { createLoopOps } from './runtime/loop-ops.js';
+export { createOrchestrateOps } from './runtime/orchestrate-ops.js';
+export { createGradingOps } from './runtime/grading-ops.js';
+export { createCaptureOps } from './runtime/capture-ops.js';
+export { createCuratorExtraOps } from './runtime/curator-extra-ops.js';
+export { createProjectOps } from './runtime/project-ops.js';
+export { createMemoryCrossProjectOps } from './runtime/memory-cross-project-ops.js';
 export type { AgentRuntimeConfig, AgentRuntime } from './runtime/types.js';

package/src/llm/llm-client.ts

@@ -11,12 +11,7 @@ import * as path from 'node:path';
 import { homedir } from 'node:os';
 import { LLMError } from './types.js';
 import { CircuitBreaker, retry, parseRateLimitHeaders } from './utils.js';
-import type {
-  LLMCallOptions,
-  LLMCallResult,
-  RouteEntry,
-  RoutingConfig,
-} from './types.js';
+import type { LLMCallOptions, LLMCallResult, RouteEntry, RoutingConfig } from './types.js';
 import type { KeyPool } from './key-pool.js';
 
 // =============================================================================
@@ -69,7 +64,11 @@ class ModelRouter {
   private config: RoutingConfig;
 
   constructor(config?: RoutingConfig) {
-    this.config = config ?? { routes: [], defaultOpenAIModel: 'gpt-4o-mini', defaultAnthropicModel: 'claude-sonnet-4-20250514' };
+    this.config = config ?? {
+      routes: [],
+      defaultOpenAIModel: 'gpt-4o-mini',
+      defaultAnthropicModel: 'claude-sonnet-4-20250514',
+    };
   }
 
   resolve(
@@ -78,17 +77,13 @@ class ModelRouter {
     originalModel?: string,
   ): { model: string; provider: 'openai' | 'anthropic' } {
     if (task) {
-      const exactMatch = this.config.routes.find(
-        (r) => r.caller === caller && r.task === task,
-      );
+      const exactMatch = this.config.routes.find((r) => r.caller === caller && r.task === task);
       if (exactMatch) {
         return { model: exactMatch.model, provider: exactMatch.provider };
       }
     }
 
-    const callerMatch = this.config.routes.find(
-      (r) => r.caller === caller && !r.task,
-    );
+    const callerMatch = this.config.routes.find((r) => r.caller === caller && !r.task);
     if (callerMatch) {
       return { model: callerMatch.model, provider: callerMatch.provider };
     }
@@ -148,11 +143,7 @@ export class LLMClient {
   }
 
   async complete(options: LLMCallOptions): Promise<LLMCallResult> {
-    const routed = this.router.resolve(
-      options.caller,
-      options.task,
-      options.model,
-    );
+    const routed = this.router.resolve(options.caller, options.task, options.model);
     const resolvedOptions = { ...options, model: routed.model, provider: routed.provider };
 
     return resolvedOptions.provider === 'anthropic'
@@ -219,10 +210,10 @@ export class LLMClient {
         }
 
         const errorBody = await response.text();
-        throw new LLMError(
-          `OpenAI API error: ${response.status} - ${errorBody}`,
-          { retryable: response.status === 429 || response.status >= 500, statusCode: response.status },
-        );
+        throw new LLMError(`OpenAI API error: ${response.status} - ${errorBody}`, {
+          retryable: response.status === 429 || response.status >= 500,
+          statusCode: response.status,
+        });
       }
 
       const data = (await response.json()) as {
@@ -270,7 +261,8 @@ export class LLMClient {
 
           const text = response.content
             .filter(
-              (block): block is { type: 'text'; text: string } => block.type === 'text' && typeof block.text === 'string',
+              (block): block is { type: 'text'; text: string } =>
+                block.type === 'text' && typeof block.text === 'string',
             )
             .map((block) => block.text)
             .join('\n');
@@ -305,7 +297,9 @@ export class LLMClient {
     try {
       // Dynamic import — @anthropic-ai/sdk is an optional peer dep.
       // eslint-disable-next-line @typescript-eslint/no-require-imports
-      const mod = await (Function('return import("@anthropic-ai/sdk")')() as Promise<{ default: new (opts: { apiKey: string }) => AnthropicClient }>);
+      const mod = await (Function('return import("@anthropic-ai/sdk")')() as Promise<{
+        default: new (opts: { apiKey: string }) => AnthropicClient;
+      }>);
       this.anthropicClient = new mod.default({ apiKey: currentKey });
       return this.anthropicClient;
     } catch {

package/src/logging/logger.ts

@@ -0,0 +1,154 @@
+/**
+ * Structured logger for Soleri agents.
+ *
+ * All output routes through stderr (stdout is reserved for MCP JSON-RPC).
+ * Supports optional file logging with daily rotation and 7-day retention.
+ *
+ * Ported from Salvador MCP's src/utils/logger.ts.
+ */
+
+import { appendFileSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import type { LogLevel, LogContext, LoggerConfig } from './types.js';
+
+const LEVEL_ORDER: LogLevel[] = ['debug', 'info', 'warn', 'error'];
+
+// MCP stdio servers must keep stdout clean for JSON-RPC.
+// Route ALL log levels through stderr (console.error/console.warn).
+const LEVEL_METHODS: Record<LogLevel, 'warn' | 'error'> = {
+  debug: 'error',
+  info: 'error',
+  warn: 'warn',
+  error: 'error',
+};
+
+/** Max age for log files before auto-pruning (7 days) */
+const LOG_RETENTION_DAYS = 7;
+
+export class Logger {
+  private readonly prefix: string;
+  private readonly minLevel: number;
+  private fileLogDir: string | null = null;
+  private fileLogPrefix: string;
+  private currentLogDate: string | null = null;
+  private currentLogPath: string | null = null;
+
+  constructor(config?: LoggerConfig) {
+    this.prefix = config?.prefix ?? '[Soleri]';
+    this.fileLogPrefix = 'agent';
+    const envLevel = process.env.SOLERI_LOG_LEVEL as LogLevel | undefined;
+    const level = config?.level ?? envLevel ?? 'info';
+    const levelIndex = LEVEL_ORDER.indexOf(level);
+    this.minLevel = levelIndex >= 0 ? levelIndex : LEVEL_ORDER.indexOf('info');
+
+    if (config?.fileLogDir) {
+      this.enableFileLog(config.fileLogDir);
+    }
+  }
+
+  /**
+   * Enable file-based logging. Output is teed to
+   * {dir}/{prefix}-YYYY-MM-DD.log in addition to stderr.
+   * Automatically prunes log files older than 7 days.
+   */
+  enableFileLog(dir: string, prefix?: string): void {
+    mkdirSync(dir, { recursive: true });
+    this.fileLogDir = dir;
+    if (prefix) this.fileLogPrefix = prefix;
+    this.rotateFileIfNeeded();
+    this.pruneOldLogs();
+  }
+
+  debug(message: string, context?: LogContext): void {
+    this.log('debug', message, context);
+  }
+
+  info(message: string, context?: LogContext): void {
+    this.log('info', message, context);
+  }
+
+  warn(message: string, context?: LogContext): void {
+    this.log('warn', message, context);
+  }
+
+  error(message: string, context?: LogContext): void {
+    this.log('error', message, context);
+  }
+
+  private log(level: LogLevel, message: string, context?: LogContext): void {
+    if (LEVEL_ORDER.indexOf(level) < this.minLevel) return;
+    const method = LEVEL_METHODS[level];
+    const tag = level.toUpperCase();
+
+    // Console output (stderr)
+    if (context) {
+      console[method](`${this.prefix}[${tag}] ${message}`, context);
+    } else {
+      console[method](`${this.prefix}[${tag}] ${message}`);
+    }
+
+    // File output (if enabled)
+    if (this.fileLogDir) {
+      this.writeToFile(tag, message, context);
+    }
+  }
+
+  private writeToFile(tag: string, message: string, context?: LogContext): void {
+    this.rotateFileIfNeeded();
+    if (!this.currentLogPath) return;
+
+    const ts = new Date().toISOString();
+    let line = `${ts} [${tag}] ${message}`;
+    if (context) {
+      try {
+        line += ' ' + JSON.stringify(context);
+      } catch {
+        // Skip unserializable context
+      }
+    }
+    try {
+      appendFileSync(this.currentLogPath, line + '\n');
+    } catch {
+      // Silently fail — file logging should never break the app
+    }
+  }
+
+  /** Switch to a new log file if the date has changed */
+  private rotateFileIfNeeded(): void {
+    if (!this.fileLogDir) return;
+    const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+    if (today !== this.currentLogDate) {
+      this.currentLogDate = today;
+      this.currentLogPath = join(this.fileLogDir, `${this.fileLogPrefix}-${today}.log`);
+    }
+  }
+
+  /** Remove log files older than LOG_RETENTION_DAYS */
+  private pruneOldLogs(): void {
+    if (!this.fileLogDir) return;
+    const prefix = this.fileLogPrefix;
+    try {
+      const cutoff = Date.now() - LOG_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+      const files = readdirSync(this.fileLogDir);
+      for (const file of files) {
+        if (!file.startsWith(`${prefix}-`) || !file.endsWith('.log')) continue;
+        const dateStr = file.slice(`${prefix}-`.length, -'.log'.length);
+        const fileDate = new Date(dateStr).getTime();
+        if (!isNaN(fileDate) && fileDate < cutoff) {
+          try {
+            unlinkSync(join(this.fileLogDir, file));
+          } catch {
+            // Ignore individual file deletion errors
+          }
+        }
+      }
+    } catch {
+      // Ignore pruning errors
+    }
+  }
+}
+
+/** Factory function for creating a logger. */
+export function createLogger(config?: LoggerConfig): Logger {
+  return new Logger(config);
+}

package/src/logging/types.ts

@@ -0,0 +1,21 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface LogContext {
+  [key: string]: unknown;
+}
+
+export interface LogEntry {
+  level: LogLevel;
+  message: string;
+  context?: LogContext;
+  timestamp: string;
+}
+
+export interface LoggerConfig {
+  /** Minimum log level. Default: 'info' (or SOLERI_LOG_LEVEL env var) */
+  level?: LogLevel;
+  /** Prefix for log messages. Default: '[Soleri]' */
+  prefix?: string;
+  /** Directory for file logging. If set, enables file output on construction. */
+  fileLogDir?: string;
+}

package/src/loop/loop-manager.ts

@@ -0,0 +1,130 @@
+/**
+ * Loop manager — lightweight in-memory state tracker for iterative
+ * validation loops.
+ *
+ * Tracks active loop, iteration history, and past loop results.
+ * Session-scoped (no persistence across restarts).
+ */
+
+import type { LoopConfig, LoopIteration, LoopState } from './types.js';
+
+export class LoopManager {
+  private activeLoop: LoopState | null = null;
+  private completedLoops: LoopState[] = [];
+
+  /**
+   * Start a new validation loop.
+   * Throws if a loop is already active.
+   */
+  startLoop(config: LoopConfig): LoopState {
+    if (this.activeLoop) {
+      throw new Error(
+        `Loop already active: ${this.activeLoop.id} (mode: ${this.activeLoop.config.mode}). ` +
+          'Cancel or complete it first.',
+      );
+    }
+
+    const loop: LoopState = {
+      id: `loop-${Date.now()}`,
+      config,
+      iterations: [],
+      status: 'active',
+      startedAt: new Date().toISOString(),
+    };
+
+    this.activeLoop = loop;
+    return loop;
+  }
+
+  /**
+   * Record an iteration result on the active loop.
+   * If the iteration passes, the loop status is NOT automatically changed —
+   * call `completeLoop()` explicitly when validation is confirmed.
+   * If max iterations reached and this iteration fails, status becomes 'max-iterations'.
+   */
+  iterate(result: {
+    validationScore?: number;
+    validationResult?: string;
+    passed: boolean;
+  }): LoopIteration {
+    if (!this.activeLoop) {
+      throw new Error('No active loop. Start one first.');
+    }
+
+    const iteration: LoopIteration = {
+      iteration: this.activeLoop.iterations.length + 1,
+      timestamp: new Date().toISOString(),
+      validationScore: result.validationScore,
+      validationResult: result.validationResult,
+      passed: result.passed,
+    };
+
+    this.activeLoop.iterations.push(iteration);
+
+    // Auto-transition to max-iterations if limit reached and not passing
+    if (
+      !result.passed &&
+      this.activeLoop.iterations.length >= this.activeLoop.config.maxIterations
+    ) {
+      this.activeLoop.status = 'max-iterations';
+      this.activeLoop.completedAt = new Date().toISOString();
+      this.completedLoops.push(this.activeLoop);
+      this.activeLoop = null;
+    }
+
+    return iteration;
+  }
+
+  /**
+   * Mark the active loop as completed (validation passed).
+   */
+  completeLoop(): LoopState {
+    if (!this.activeLoop) {
+      throw new Error('No active loop to complete.');
+    }
+
+    this.activeLoop.status = 'completed';
+    this.activeLoop.completedAt = new Date().toISOString();
+    const completed = this.activeLoop;
+    this.completedLoops.push(completed);
+    this.activeLoop = null;
+    return completed;
+  }
+
+  /**
+   * Cancel the active loop.
+   */
+  cancelLoop(): LoopState {
+    if (!this.activeLoop) {
+      throw new Error('No active loop to cancel.');
+    }
+
+    this.activeLoop.status = 'cancelled';
+    this.activeLoop.completedAt = new Date().toISOString();
+    const cancelled = this.activeLoop;
+    this.completedLoops.push(cancelled);
+    this.activeLoop = null;
+    return cancelled;
+  }
+
+  /**
+   * Get current loop status. Returns null if no active loop.
+   */
+  getStatus(): LoopState | null {
+    return this.activeLoop;
+  }
+
+  /**
+   * Get history of all completed/cancelled/max-iterations loops.
+   */
+  getHistory(): LoopState[] {
+    return [...this.completedLoops];
+  }
+
+  /**
+   * Check if a loop is currently active.
+   */
+  isActive(): boolean {
+    return this.activeLoop !== null;
+  }
+}