zouroboros-core 2.0.0

package/dist/types.d.ts

@@ -0,0 +1,406 @@
+/**
+ * Core types for Zouroboros
+ *
+ * This file defines all shared types used across the Zouroboros ecosystem.
+ */
+export type UUID = string;
+export type Timestamp = string;
+export type DecayClass = 'permanent' | 'long' | 'medium' | 'short';
+export interface ZouroborosConfig {
+    version: string;
+    createdAt: Timestamp;
+    updatedAt: Timestamp;
+    core: CoreConfig;
+    memory: MemoryConfig;
+    swarm: SwarmConfig;
+    personas: PersonasConfig;
+    selfheal: SelfHealConfig;
+}
+export interface CoreConfig {
+    workspaceRoot: string;
+    dataDir: string;
+    logLevel: 'debug' | 'info' | 'warn' | 'error';
+    defaultTimezone: string;
+}
+export interface MemoryConfig {
+    enabled: boolean;
+    dbPath: string;
+    vectorEnabled: boolean;
+    ollamaUrl: string;
+    ollamaModel: string;
+    autoCapture: boolean;
+    captureIntervalMinutes: number;
+    graphBoost: boolean;
+    hydeExpansion: boolean;
+    decayConfig: {
+        permanent: number;
+        long: number;
+        medium: number;
+        short: number;
+    };
+}
+export interface SwarmConfig {
+    enabled: boolean;
+    defaultCombo: string;
+    maxConcurrency: number;
+    localConcurrency: number;
+    circuitBreaker: {
+        enabled: boolean;
+        failureThreshold: number;
+        resetTimeoutMs: number;
+    };
+    retryConfig: {
+        maxRetries: number;
+        backoffMultiplier: number;
+        maxBackoffMs: number;
+    };
+    registryPath: string;
+}
+export interface PersonasConfig {
+    enabled: boolean;
+    identityDir: string;
+    defaultSoulPath: string;
+    autoCreateHeartbeat: boolean;
+}
+export interface SelfHealConfig {
+    enabled: boolean;
+    introspectionInterval: string;
+    autoPrescribe: boolean;
+    governorEnabled: boolean;
+    minHealthScore: number;
+    metrics: Record<string, MetricThreshold>;
+}
+export interface MetricThreshold {
+    target: number;
+    weight: number;
+    warningThreshold: number;
+    criticalThreshold: number;
+}
+export interface MemoryEntry {
+    id: UUID;
+    entity: string;
+    key: string | null;
+    value: string;
+    decay: DecayClass;
+    createdAt: Timestamp;
+    updatedAt: Timestamp;
+    embedding?: number[];
+    tags?: string[];
+}
+export interface EpisodicMemory {
+    id: UUID;
+    conversationId: string;
+    summary: string;
+    outcome: 'success' | 'failure' | 'partial' | 'resolved' | 'ongoing';
+    entities: string[];
+    tags: string[];
+    createdAt: Timestamp;
+    tokenCount?: number;
+}
+export interface TemporalQuery {
+    since?: string;
+    until?: string;
+    outcome?: string;
+    limit?: number;
+}
+export interface ProceduralMemory {
+    id: UUID;
+    name: string;
+    description: string;
+    steps: string[];
+    successRate: number;
+    lastExecuted?: Timestamp;
+    executionCount: number;
+}
+export interface CognitiveProfile {
+    entity: string;
+    traits: Record<string, number>;
+    preferences: Record<string, string>;
+    interactionHistory: InteractionRecord[];
+    lastUpdated: Timestamp;
+}
+export interface InteractionRecord {
+    timestamp: Timestamp;
+    type: 'query' | 'store' | 'search';
+    success: boolean;
+    latencyMs: number;
+}
+export interface MemorySearchResult {
+    entry: MemoryEntry;
+    score: number;
+    matchType: 'exact' | 'semantic' | 'graph' | 'hybrid';
+}
+export interface GraphNode {
+    id: string;
+    type: 'entity' | 'concept' | 'fact';
+    label: string;
+    properties: Record<string, unknown>;
+}
+export interface GraphEdge {
+    source: string;
+    target: string;
+    relation: string;
+    weight: number;
+}
+export interface SwarmCampaign {
+    id: UUID;
+    name: string;
+    description: string;
+    tasks: SwarmTask[];
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    createdAt: Timestamp;
+    startedAt?: Timestamp;
+    completedAt?: Timestamp;
+}
+export interface SwarmTask {
+    id: UUID;
+    name: string;
+    description: string;
+    dependencies: string[];
+    executor: 'local';
+    localExecutor?: string;
+    prompt: string;
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    output?: string;
+    error?: string;
+    startedAt?: Timestamp;
+    completedAt?: Timestamp;
+    tokenUsage?: TokenUsage;
+}
+export interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    costUsd: number;
+}
+export interface ExecutorBridge {
+    name: string;
+    type: 'local' | 'remote';
+    command: string;
+    healthCheck: string;
+    envVars: string[];
+    supportedModels?: string[];
+}
+export interface ExecutorRegistry {
+    version: string;
+    updatedAt: Timestamp;
+    executors: Record<string, ExecutorConfig>;
+}
+export interface ExecutorConfig {
+    name: string;
+    bridge: string;
+    healthCheck: string;
+    timeoutSeconds: number;
+    envVars: Record<string, string>;
+}
+export interface ComboRecommendation {
+    complexity: ComplexityAnalysis;
+    recommendedCombo: ModelCombo;
+    alternatives: ComboAlternative[];
+    resolvedCombo: string;
+}
+export interface ComplexityAnalysis {
+    tier: 'trivial' | 'simple' | 'moderate' | 'complex';
+    score: number;
+    signals: ComplexitySignals;
+    inferredTaskType: TaskType;
+    staticCombo: string;
+}
+export interface ComplexitySignals {
+    wordCount: number;
+    fileCount: number;
+    hasMultiStep: boolean;
+    hasTool: boolean;
+    hasAnalysis: boolean;
+}
+export type TaskType = 'coding' | 'review' | 'planning' | 'analysis' | 'debugging' | 'documentation' | 'general';
+export interface ModelCombo {
+    id: string;
+    name: string;
+    description: string;
+    models: ModelConfig[];
+    estimatedCostPer1M: number;
+    traits: string[];
+}
+export interface ModelConfig {
+    provider: string;
+    model: string;
+    inputCostPer1M: number;
+    outputCostPer1M: number;
+}
+export interface ComboAlternative {
+    name: string;
+    score: number;
+    isFree: boolean;
+}
+export interface SeedSpec {
+    id: string;
+    createdAt: Timestamp;
+    goal: string;
+    constraints: string[];
+    acceptanceCriteria: string[];
+    ontology: OntologyDef;
+    evaluationPrinciples: EvaluationPrinciple[];
+    exitConditions: ExitCondition[];
+    ambiguityScore: number;
+}
+export interface OntologyDef {
+    name: string;
+    description: string;
+    fields: OntologyField[];
+}
+export interface OntologyField {
+    name: string;
+    type: string;
+    description: string;
+}
+export interface EvaluationPrinciple {
+    name: string;
+    description: string;
+    weight: number;
+}
+export interface ExitCondition {
+    name: string;
+    description: string;
+    criteria: string;
+}
+export interface EvaluationReport {
+    id: string;
+    seedId: string;
+    timestamp: Timestamp;
+    stages: {
+        mechanical: MechanicalStage;
+        semantic: SemanticStage;
+        consensus?: ConsensusStage;
+    };
+    decision: 'APPROVED' | 'NEEDS_WORK' | 'REJECTED';
+    recommendations: string[];
+}
+export interface MechanicalStage {
+    passed: boolean;
+    checks: MechanicalCheck[];
+}
+export interface MechanicalCheck {
+    name: string;
+    passed: boolean;
+    detail?: string;
+}
+export interface SemanticStage {
+    passed: boolean;
+    score: number;
+    acCompliance: number;
+    drift: number;
+    criteria: CriterionResult[];
+}
+export interface CriterionResult {
+    name: string;
+    met: boolean;
+    evidence?: string;
+}
+export interface ConsensusStage {
+    perspectives: Perspective[];
+    finalDecision: 'APPROVE' | 'REJECT';
+    reasoning: string;
+}
+export interface Perspective {
+    role: 'proposer' | 'devils_advocate' | 'synthesizer';
+    decision: 'APPROVE' | 'REJECT';
+    reasoning: string;
+}
+export type UnstuckPersona = 'hacker' | 'researcher' | 'simplifier' | 'architect' | 'contrarian';
+export interface Persona {
+    id: UUID;
+    name: string;
+    description: string;
+    prompt: string;
+    safetyRules: SafetyRule[];
+    skills: string[];
+    mcpServers: string[];
+    identityFiles?: {
+        soul?: string;
+        identity?: string;
+        user?: string;
+        heartbeat?: string;
+    };
+    createdAt: Timestamp;
+    updatedAt: Timestamp;
+}
+export interface SafetyRule {
+    id: string;
+    condition: string;
+    instruction: string;
+    priority: 'critical' | 'high' | 'medium' | 'low';
+}
+export interface IdentityFile {
+    type: 'soul' | 'identity' | 'user' | 'heartbeat';
+    path: string;
+    content: string;
+    lastUpdated: Timestamp;
+}
+export interface IntrospectionScorecard {
+    id: string;
+    timestamp: Timestamp;
+    compositeScore: number;
+    metrics: MetricScore[];
+    status: 'HEALTHY' | 'WARNING' | 'CRITICAL';
+    weakestSubsystem: string;
+    opportunities: ImprovementOpportunity[];
+}
+export interface MetricScore {
+    name: string;
+    score: number;
+    target: number;
+    weight: number;
+    trend: 'improving' | 'stable' | 'declining';
+    status: 'HEALTHY' | 'WARNING' | 'CRITICAL';
+}
+export interface ImprovementOpportunity {
+    rank: number;
+    metric: string;
+    currentScore: number;
+    potentialImprovement: number;
+    recommendedAction: string;
+}
+export interface Prescription {
+    id: string;
+    scorecardId: string;
+    targetMetric: string;
+    seed: SeedSpec;
+    program?: AutoloopProgram;
+    governorFlags: GovernorFlag[];
+    approved: boolean;
+    createdAt: Timestamp;
+}
+export interface GovernorFlag {
+    type: 'schema_migration' | 'multi_file' | 'executor_change' | 'high_ambiguity' | 'no_baseline';
+    severity: 'warning' | 'block';
+    description: string;
+}
+export interface AutoloopProgram {
+    name: string;
+    metric: string;
+    targetFile: string;
+    runCommand: string;
+    extractCommand: string;
+    maxExperiments: number;
+    maxDurationHours: number;
+    maxCostUsd: number;
+}
+export interface EvolutionResult {
+    id: string;
+    prescriptionId: string;
+    status: 'success' | 'failure' | 'reverted';
+    baselineValue: number;
+    finalValue: number;
+    improvement: number;
+    experiments: ExperimentRecord[];
+    startedAt: Timestamp;
+    completedAt?: Timestamp;
+}
+export interface ExperimentRecord {
+    id: number;
+    change: string;
+    value: number;
+    improved: boolean;
+    committed: boolean;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Core types for Zouroboros
+ *
+ * This file defines all shared types used across the Zouroboros ecosystem.
+ */
+export {};

package/dist/utils/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Utility functions for Zouroboros
+ */
+/**
+ * Generate a UUID v4
+ */
+export declare function generateUUID(): string;
+/**
+ * Get current timestamp in ISO format
+ */
+export declare function now(): string;
+/**
+ * Deep clone an object
+ */
+export declare function deepClone<T>(obj: T): T;
+/**
+ * Sleep for a given number of milliseconds
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Retry a function with exponential backoff
+ */
+export declare function retry<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    backoffMultiplier?: number;
+    maxBackoffMs?: number;
+    onRetry?: (error: Error, attempt: number) => void;
+}): Promise<T>;
+/**
+ * Format bytes to human readable string
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Format milliseconds to human readable duration
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Truncate a string to a maximum length
+ */
+export declare function truncate(str: string, maxLength: number, suffix?: string): string;
+/**
+ * Parse a cron expression (simplified - only supports basic patterns)
+ */
+export declare function parseCron(expression: string): {
+    minute: number;
+    hour: number;
+};
+/**
+ * Check if a value is a plain object
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Merge two objects deeply
+ */
+export declare function deepMerge<T extends Record<string, unknown>>(target: T, source: Partial<T>): T;

package/dist/utils/index.js

@@ -0,0 +1,132 @@
+/**
+ * Utility functions for Zouroboros
+ */
+import { randomUUID } from 'crypto';
+/**
+ * Generate a UUID v4
+ */
+export function generateUUID() {
+    return randomUUID();
+}
+/**
+ * Get current timestamp in ISO format
+ */
+export function now() {
+    return new Date().toISOString();
+}
+/**
+ * Deep clone an object
+ */
+export function deepClone(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}
+/**
+ * Sleep for a given number of milliseconds
+ */
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Retry a function with exponential backoff
+ */
+export async function retry(fn, options = {}) {
+    const { maxRetries = 3, backoffMultiplier = 2, maxBackoffMs = 30000, onRetry } = options;
+    let lastError = new Error('No attempts made');
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            if (attempt === maxRetries) {
+                throw lastError;
+            }
+            if (onRetry) {
+                onRetry(lastError, attempt + 1);
+            }
+            const backoffMs = Math.min(1000 * Math.pow(backoffMultiplier, attempt), maxBackoffMs);
+            await sleep(backoffMs);
+        }
+    }
+    throw lastError;
+}
+/**
+ * Format bytes to human readable string
+ */
+export function formatBytes(bytes) {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let size = bytes;
+    let unitIndex = 0;
+    while (size >= 1024 && unitIndex < units.length - 1) {
+        size /= 1024;
+        unitIndex++;
+    }
+    return `${size.toFixed(2)} ${units[unitIndex]}`;
+}
+/**
+ * Format milliseconds to human readable duration
+ */
+export function formatDuration(ms) {
+    if (ms < 1000) {
+        return `${ms}ms`;
+    }
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60) {
+        return `${seconds}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    if (minutes < 60) {
+        return `${minutes}m ${remainingSeconds}s`;
+    }
+    const hours = Math.floor(minutes / 60);
+    const remainingMinutes = minutes % 60;
+    return `${hours}h ${remainingMinutes}m`;
+}
+/**
+ * Truncate a string to a maximum length
+ */
+export function truncate(str, maxLength, suffix = '...') {
+    if (str.length <= maxLength) {
+        return str;
+    }
+    return str.slice(0, maxLength - suffix.length) + suffix;
+}
+/**
+ * Parse a cron expression (simplified - only supports basic patterns)
+ */
+export function parseCron(expression) {
+    const parts = expression.split(' ');
+    if (parts.length < 2) {
+        throw new Error('Invalid cron expression');
+    }
+    const minute = parts[0] === '*' ? 0 : parseInt(parts[0], 10);
+    const hour = parts[1] === '*' ? 0 : parseInt(parts[1], 10);
+    if (isNaN(minute) || isNaN(hour)) {
+        throw new Error('Invalid cron expression');
+    }
+    return { minute, hour };
+}
+/**
+ * Check if a value is a plain object
+ */
+export function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Merge two objects deeply
+ */
+export function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key in source) {
+        if (source[key] !== undefined) {
+            if (isPlainObject(result[key]) && isPlainObject(source[key])) {
+                result[key] = deepMerge(result[key], source[key]);
+            }
+            else {
+                result[key] = source[key];
+            }
+        }
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "zouroboros-core",
+  "version": "2.0.0",
+  "description": "Core types, configuration, and utilities for Zouroboros",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./config": {
+      "import": "./dist/config/loader.js",
+      "types": "./dist/config/loader.d.ts"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "keywords": [
+    "zouroboros",
+    "core",
+    "config",
+    "types"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marlandoj/zouroboros.git",
+    "directory": "packages/core"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test src/",
+    "test:coverage": "bun test --coverage src/",
+    "lint": "eslint src --ext .ts",
+    "clean": "rm -rf dist"
+  }
+}