@sidurijs/core 1.0.0

package/dist/schema-validator.d.ts

@@ -0,0 +1,9 @@
+export declare class ConfigValidationError extends Error {
+    errors: string[];
+    constructor(errors: string[]);
+}
+/**
+ * Validates a companion configuration object against a JSON schema (draft-07 compatible).
+ * Throws ConfigValidationError if validation errors are detected.
+ */
+export declare function validateCompanionConfig(config: unknown, schema: any, path?: string): void;

package/dist/schema-validator.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigValidationError = void 0;
+exports.validateCompanionConfig = validateCompanionConfig;
+class ConfigValidationError extends Error {
+    errors;
+    constructor(errors) {
+        super(`Siduri configuration validation failed:\n${errors.map((e) => `  - ${e}`).join('\n')}`);
+        this.name = 'ConfigValidationError';
+        this.errors = errors;
+    }
+}
+exports.ConfigValidationError = ConfigValidationError;
+/**
+ * Validates a companion configuration object against a JSON schema (draft-07 compatible).
+ * Throws ConfigValidationError if validation errors are detected.
+ */
+function validateCompanionConfig(config, schema, path = '$') {
+    const errors = [];
+    function validateNode(value, nodeSchema, curPath) {
+        if (!nodeSchema || typeof nodeSchema !== 'object')
+            return;
+        // Type validation
+        if (nodeSchema.type !== undefined) {
+            const type = nodeSchema.type;
+            if (type === 'object') {
+                if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+                    errors.push(`${curPath}: expected object, received ${value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value}`);
+                    return;
+                }
+            }
+            else if (type === 'array') {
+                if (!Array.isArray(value)) {
+                    errors.push(`${curPath}: expected array, received ${typeof value}`);
+                    return;
+                }
+            }
+            else if (type === 'string') {
+                if (typeof value !== 'string') {
+                    errors.push(`${curPath}: expected string, received ${typeof value}`);
+                    return;
+                }
+            }
+            else if (type === 'number') {
+                if (typeof value !== 'number' || Number.isNaN(value)) {
+                    errors.push(`${curPath}: expected number, received ${typeof value}`);
+                    return;
+                }
+            }
+            else if (type === 'integer') {
+                if (typeof value !== 'number' || !Number.isInteger(value)) {
+                    errors.push(`${curPath}: expected integer, received ${typeof value}`);
+                    return;
+                }
+            }
+            else if (type === 'boolean') {
+                if (typeof value !== 'boolean') {
+                    errors.push(`${curPath}: expected boolean, received ${typeof value}`);
+                    return;
+                }
+            }
+        }
+        // Enum validation
+        if (Array.isArray(nodeSchema.enum)) {
+            if (!nodeSchema.enum.includes(value)) {
+                errors.push(`${curPath}: invalid value ${JSON.stringify(value)}, expected one of: ${nodeSchema.enum.map((v) => JSON.stringify(v)).join(', ')}`);
+                return;
+            }
+        }
+        // Object properties validation
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            if (Array.isArray(nodeSchema.required)) {
+                for (const reqKey of nodeSchema.required) {
+                    if (value[reqKey] === undefined) {
+                        errors.push(`${curPath}.${reqKey}: is required`);
+                    }
+                }
+            }
+            const definedProps = nodeSchema.properties || {};
+            if (nodeSchema.additionalProperties === false) {
+                for (const key of Object.keys(value)) {
+                    // Allow $schema property at root level
+                    if (curPath === '$' && key === '$schema')
+                        continue;
+                    if (!(key in definedProps)) {
+                        errors.push(`${curPath}.${key}: unexpected property is not allowed`);
+                    }
+                }
+            }
+            for (const [propName, propSchema] of Object.entries(definedProps)) {
+                if (value[propName] !== undefined) {
+                    validateNode(value[propName], propSchema, `${curPath}.${propName}`);
+                }
+            }
+        }
+        // Array items validation
+        if (Array.isArray(value) && nodeSchema.items) {
+            value.forEach((item, index) => {
+                validateNode(item, nodeSchema.items, `${curPath}[${index}]`);
+            });
+        }
+    }
+    validateNode(config, schema, path);
+    if (errors.length > 0) {
+        throw new ConfigValidationError(errors);
+    }
+}

package/dist/schema-validator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/schema-validator.test.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const schema_validator_1 = require("./schema-validator");
+describe('validateCompanionConfig', () => {
+    const sampleSchema = {
+        type: 'object',
+        required: ['id', 'name', 'organs'],
+        additionalProperties: false,
+        properties: {
+            $schema: { type: 'string' },
+            id: { type: 'string' },
+            name: { type: 'string' },
+            organs: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    brain: {
+                        type: 'object',
+                        required: ['provider', 'model'],
+                        properties: {
+                            provider: {
+                                type: 'string',
+                                enum: ['openrouter', 'openai-compatible'],
+                            },
+                            model: { type: 'string' },
+                        },
+                    },
+                    memory: {
+                        type: 'object',
+                        required: ['provider'],
+                        properties: {
+                            provider: {
+                                type: 'string',
+                                enum: ['sqlite', 'in-memory', 'none'],
+                            },
+                            maxConnections: { type: 'number' },
+                        },
+                    },
+                },
+            },
+        },
+    };
+    test('accepts valid configuration matching schema', () => {
+        const validConfig = {
+            $schema: './siduri.schema.json',
+            id: 'companion-1',
+            name: 'Test Companion',
+            organs: {
+                brain: {
+                    provider: 'openrouter',
+                    model: 'gpt-4o',
+                },
+            },
+        };
+        expect(() => (0, schema_validator_1.validateCompanionConfig)(validConfig, sampleSchema)).not.toThrow();
+    });
+    test('throws ConfigValidationError if missing required root field', () => {
+        const invalidConfig = {
+            name: 'Missing Id and Organs',
+        };
+        expect(() => (0, schema_validator_1.validateCompanionConfig)(invalidConfig, sampleSchema)).toThrow(schema_validator_1.ConfigValidationError);
+        try {
+            (0, schema_validator_1.validateCompanionConfig)(invalidConfig, sampleSchema);
+        }
+        catch (err) {
+            expect(err.errors).toContain('$.id: is required');
+            expect(err.errors).toContain('$.organs: is required');
+        }
+    });
+    test('throws ConfigValidationError on unexpected property when additionalProperties is false', () => {
+        const invalidConfig = {
+            id: 'c-1',
+            name: 'Test',
+            organs: {},
+            extraField: 'not allowed',
+        };
+        expect(() => (0, schema_validator_1.validateCompanionConfig)(invalidConfig, sampleSchema)).toThrow(schema_validator_1.ConfigValidationError);
+        try {
+            (0, schema_validator_1.validateCompanionConfig)(invalidConfig, sampleSchema);
+        }
+        catch (err) {
+            expect(err.errors).toContain('$.extraField: unexpected property is not allowed');
+        }
+    });
+    test('throws ConfigValidationError on invalid enum value', () => {
+        const invalidConfig = {
+            id: 'c-1',
+            name: 'Test',
+            organs: {
+                brain: {
+                    provider: 'invalid-brain-provider',
+                    model: 'gpt-4',
+                },
+            },
+        };
+        expect(() => (0, schema_validator_1.validateCompanionConfig)(invalidConfig, sampleSchema)).toThrow(schema_validator_1.ConfigValidationError);
+        try {
+            (0, schema_validator_1.validateCompanionConfig)(invalidConfig, sampleSchema);
+        }
+        catch (err) {
+            expect(err.errors.some((e) => e.includes('invalid value "invalid-brain-provider"'))).toBe(true);
+        }
+    });
+    test('throws ConfigValidationError on invalid type', () => {
+        const invalidConfig = {
+            id: 12345, // should be string
+            name: 'Test',
+            organs: {
+                memory: {
+                    provider: 'sqlite',
+                    maxConnections: 'ten', // should be number
+                },
+            },
+        };
+        expect(() => (0, schema_validator_1.validateCompanionConfig)(invalidConfig, sampleSchema)).toThrow(schema_validator_1.ConfigValidationError);
+        try {
+            (0, schema_validator_1.validateCompanionConfig)(invalidConfig, sampleSchema);
+        }
+        catch (err) {
+            expect(err.errors).toContain('$.id: expected string, received number');
+            expect(err.errors).toContain('$.organs.memory.maxConnections: expected number, received string');
+        }
+    });
+});

package/dist/session-history.d.ts

@@ -0,0 +1,20 @@
+import { Message } from './index';
+export interface SessionHistoryOptions {
+    maxSessions?: number;
+    maxMessagesPerSession?: number;
+}
+/**
+ * Manages conversation history scoped by session key to prevent cross-session
+ * and cross-channel memory/conversation leakage.
+ */
+export declare class SessionHistoryManager {
+    private readonly sessions;
+    private readonly maxSessions;
+    private readonly maxMessagesPerSession;
+    constructor(options?: SessionHistoryOptions);
+    getHistory(sessionKey?: string): Message[];
+    setHistory(sessionKey: string | undefined, history: Message[]): void;
+    append(sessionKey: string | undefined, message: Message): void;
+    clear(sessionKey?: string): void;
+    sessionCount(): number;
+}

package/dist/session-history.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionHistoryManager = void 0;
+/**
+ * Manages conversation history scoped by session key to prevent cross-session
+ * and cross-channel memory/conversation leakage.
+ */
+class SessionHistoryManager {
+    sessions = new Map();
+    maxSessions;
+    maxMessagesPerSession;
+    constructor(options = {}) {
+        this.maxSessions = options.maxSessions ?? 200;
+        this.maxMessagesPerSession = options.maxMessagesPerSession ?? 20;
+    }
+    getHistory(sessionKey = 'default') {
+        return this.sessions.get(sessionKey) || [];
+    }
+    setHistory(sessionKey = 'default', history) {
+        if (this.sessions.size >= this.maxSessions && !this.sessions.has(sessionKey)) {
+            const oldestKey = this.sessions.keys().next().value;
+            if (oldestKey) {
+                this.sessions.delete(oldestKey);
+            }
+        }
+        const bounded = history.slice(-this.maxMessagesPerSession).map((item) => ({
+            role: item.role,
+            content: item.content.slice(0, 2000).replace(/\0/g, ''),
+        }));
+        this.sessions.set(sessionKey, bounded);
+    }
+    append(sessionKey = 'default', message) {
+        const current = this.getHistory(sessionKey);
+        const updated = [
+            ...current,
+            {
+                role: message.role,
+                content: message.content.slice(0, 2000).replace(/\0/g, ''),
+            },
+        ].slice(-this.maxMessagesPerSession);
+        this.setHistory(sessionKey, updated);
+    }
+    clear(sessionKey) {
+        if (sessionKey) {
+            this.sessions.delete(sessionKey);
+        }
+        else {
+            this.sessions.clear();
+        }
+    }
+    sessionCount() {
+        return this.sessions.size;
+    }
+}
+exports.SessionHistoryManager = SessionHistoryManager;

package/dist/session-history.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/session-history.test.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const session_history_1 = require("./session-history");
+describe('SessionHistoryManager', () => {
+    test('isolates history across distinct sessions', () => {
+        const manager = new session_history_1.SessionHistoryManager();
+        manager.append('session-alice', { role: 'user', content: 'Alice message' });
+        manager.append('session-bob', { role: 'user', content: 'Bob message' });
+        expect(manager.getHistory('session-alice')).toEqual([
+            { role: 'user', content: 'Alice message' },
+        ]);
+        expect(manager.getHistory('session-bob')).toEqual([
+            { role: 'user', content: 'Bob message' },
+        ]);
+    });
+    test('bounds messages per session to configured limit and strips null bytes', () => {
+        const manager = new session_history_1.SessionHistoryManager({ maxMessagesPerSession: 3 });
+        manager.append('sess-1', { role: 'user', content: 'm1\0' });
+        manager.append('sess-1', { role: 'assistant', content: 'm2' });
+        manager.append('sess-1', { role: 'user', content: 'm3' });
+        manager.append('sess-1', { role: 'assistant', content: 'm4' });
+        const history = manager.getHistory('sess-1');
+        expect(history).toHaveLength(3);
+        expect(history[0].content).toBe('m2');
+        expect(history[2].content).toBe('m4');
+    });
+    test('bounds maximum active sessions with LRU eviction', () => {
+        const manager = new session_history_1.SessionHistoryManager({ maxSessions: 2 });
+        manager.append('sess-1', { role: 'user', content: 'm1' });
+        manager.append('sess-2', { role: 'user', content: 'm2' });
+        expect(manager.sessionCount()).toBe(2);
+        manager.append('sess-3', { role: 'user', content: 'm3' });
+        expect(manager.sessionCount()).toBe(2);
+        expect(manager.getHistory('sess-1')).toEqual([]);
+        expect(manager.getHistory('sess-2')).toHaveLength(1);
+        expect(manager.getHistory('sess-3')).toHaveLength(1);
+    });
+});

package/dist/siduri-db.d.ts

@@ -0,0 +1,235 @@
+import { ClaimStatus, DirectiveStatus } from './proposals';
+export interface SelfIdentity {
+    companionId: string;
+    name: string;
+    archetype?: string;
+    role?: string;
+    origin?: string;
+    ethos?: string;
+    version: string;
+    updatedAt: string;
+}
+export interface PersonalityTraits {
+    warmth?: number;
+    formality?: number;
+    sarcasm?: number;
+    verbosity?: number;
+    curiosity?: number;
+}
+export interface SelfDirective {
+    id: string;
+    companionId: string;
+    priority?: number;
+    directive: string;
+    status: DirectiveStatus;
+    category: 'behavioral' | 'guardrail' | 'relational' | string;
+    scopeActor?: string;
+    supersedesId?: string;
+    createdAt?: string;
+}
+export interface SelfRelationship {
+    companionId: string;
+    entityId: string;
+    entityType?: 'human' | 'companion' | 'system';
+    name?: string;
+    affiliation?: string;
+    role?: string;
+    stance?: string;
+    trustScore?: number;
+    familiarity?: number;
+    interactionConventions: string[];
+    updatedAt?: string;
+}
+export interface SelfDialogueExample {
+    id?: string;
+    companionId?: string;
+    user: string;
+    assistant: string;
+    createdAt?: string;
+}
+export interface LifeInventoryItem {
+    id: string;
+    companionId: string;
+    domain: string;
+    entityName: string;
+    properties: Record<string, unknown>;
+    updatedAt: string;
+}
+export interface LifeFinanceEntry {
+    id: string;
+    companionId: string;
+    category: string;
+    amount: number;
+    currency: string;
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+}
+export interface LifeScheduleItem {
+    id: string;
+    companionId: string;
+    title: string;
+    startTime: string;
+    endTime?: string;
+    isRecurring: boolean;
+    status: string;
+}
+export interface LifePreference {
+    id: string;
+    companionId: string;
+    preferenceKey: string;
+    preferenceValue: string;
+    category: string;
+    updatedAt: string;
+}
+export interface LifeEntity {
+    id: string;
+    companionId: string;
+    entityType: string;
+    domain: string;
+    name: string;
+    properties: Record<string, unknown>;
+    updatedAt?: string;
+}
+export interface LifeEvent {
+    id: string;
+    companionId: string;
+    stream: string;
+    timestamp?: string;
+    metricValue?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface LifeTask {
+    id: string;
+    companionId: string;
+    title: string;
+    status: 'backlog' | 'in_progress' | 'completed' | 'cancelled' | string;
+    priority?: number;
+    targetDate?: string;
+    metadata?: Record<string, unknown>;
+    updatedAt?: string;
+}
+export interface EpisodicEvent {
+    id: string;
+    companionId: string;
+    sourceType: 'chat_turn' | 'tool_result' | 'sensory';
+    occurredAt: string;
+    payload: Record<string, unknown>;
+}
+export interface MemoryClaim {
+    id: string;
+    companionId: string;
+    subject: string;
+    predicate: string;
+    value: string;
+    status: ClaimStatus;
+    confidence: number;
+    validFrom?: string;
+    validUntil?: string;
+    evidence?: string[];
+    assertedAt: string;
+    supersedes?: string;
+    sourceEventId?: string;
+}
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface SystemLog {
+    id: string;
+    companionId: string;
+    level: LogLevel;
+    subsystem: string;
+    message: string;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+}
+export declare function safeJsonParse<T = any>(str?: string | null, fallback?: T): T;
+export declare function normalizeStatus(status?: string, defaultStatus?: string): string;
+export interface SiduriDatabaseOptions {
+    dbPath?: string;
+}
+export declare class SiduriDatabase {
+    private db;
+    constructor(options?: SiduriDatabaseOptions);
+    private initSchema;
+    close(): void;
+    getIdentity(companionId: string): SelfIdentity | undefined;
+    setIdentity(identity: SelfIdentity): void;
+    getPersonality(companionId: string): PersonalityTraits | undefined;
+    setPersonality(companionId: string, traits: PersonalityTraits): void;
+    private rowToSelfDirective;
+    getActiveDirectives(companionId: string): SelfDirective[];
+    getAllDirectives(companionId: string): SelfDirective[];
+    commitDirective(directive: SelfDirective): void;
+    getDirective(id: string, companionId?: string): SelfDirective | undefined;
+    approveDirective(id: string, companionId?: string): void;
+    rejectDirective(id: string, companionId?: string): void;
+    supersedeDirective(id: string, companionId?: string): void;
+    revokeDirective(id: string, companionId?: string): void;
+    expireDirective(id: string, companionId?: string): void;
+    disableDirective(id: string, companionId?: string): void;
+    getRelationship(companionId: string, entityId: string): SelfRelationship | undefined;
+    getRelationships(companionId: string): SelfRelationship[];
+    upsertRelationship(rel: SelfRelationship): void;
+    getExemplars(companionId: string): SelfDialogueExample[];
+    setExemplars(companionId: string, exemplars: SelfDialogueExample[]): void;
+    getInventory(companionId: string, domain?: string): LifeInventoryItem[];
+    upsertInventoryItem(item: LifeInventoryItem): void;
+    getFinanceEntries(companionId: string, limit?: number): LifeFinanceEntry[];
+    addFinanceEntry(entry: LifeFinanceEntry): void;
+    getSchedule(companionId: string): LifeScheduleItem[];
+    upsertScheduleItem(item: LifeScheduleItem): void;
+    deleteScheduleItem(id: string): boolean;
+    getPreferences(companionId: string): LifePreference[];
+    upsertPreference(pref: LifePreference): void;
+    getEntities(companionId: string, entityType?: string, domain?: string): LifeEntity[];
+    getEntityById(id: string): LifeEntity | undefined;
+    upsertEntity(entity: LifeEntity): void;
+    deleteEntity(id: string): boolean;
+    getEvents(companionId: string, stream?: string, limit?: number): LifeEvent[];
+    addEvent(event: LifeEvent): void;
+    getTasks(companionId: string, status?: string): LifeTask[];
+    upsertTask(task: LifeTask): void;
+    deleteTask(id: string): boolean;
+    recordEvent(event: EpisodicEvent): void;
+    getRecentEvents(companionId: string, limit?: number): EpisodicEvent[];
+    getEvent(id: string): EpisodicEvent | undefined;
+    private rowToMemoryClaim;
+    proposeClaim(claim: Omit<MemoryClaim, 'status' | 'confidence' | 'assertedAt'> & {
+        confidence?: number;
+        assertedAt?: string;
+        supersedes?: string;
+        sourceEventId?: string;
+        status?: string;
+    }): MemoryClaim;
+    approveClaim(id: string, companionId?: string): void;
+    /**
+     * Canonically promotes a Claim into Self domain tables.
+     */
+    promoteClaimToSelf(claim: MemoryClaim | any): void;
+    rejectClaim(id: string, companionId?: string): void;
+    revokeClaim(id: string, companionId?: string): void;
+    expireClaim(id: string, companionId?: string): void;
+    markClaimSessionOnly(id: string, companionId?: string): void;
+    searchClaims(companionId: string, query: string, limit?: number): MemoryClaim[];
+    getPendingClaims(companionId: string, limit?: number): MemoryClaim[];
+    getApprovedClaims(companionId: string, limit?: number): MemoryClaim[];
+    getAllClaims(companionId?: string, limit?: number): MemoryClaim[];
+    getClaim(id: string): MemoryClaim | undefined;
+    resetMemory(companionId: string): void;
+    insertLog(entry: {
+        id?: string;
+        companionId?: string;
+        level: LogLevel | string;
+        subsystem: string;
+        message: string;
+        metadata?: Record<string, unknown>;
+        createdAt?: string;
+    }): SystemLog;
+    queryLogs(options?: {
+        companionId?: string;
+        level?: string;
+        subsystem?: string;
+        q?: string;
+        limit?: number;
+        offset?: number;
+    }): SystemLog[];
+    clearLogs(companionId?: string): void;
+}