@sidurijs/core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,367 @@
+export * from './context';
+export * from './proposals';
+export * from './evidence';
+export * from './gating';
+export * from './experience';
+export * from './dispatcher';
+export * from './action';
+export * from './action-policy';
+export * from './ear-types';
+export * from './capability';
+export * from './sqlite-action-store';
+export * from './teaching';
+export * from './runtime';
+export * from './chat-contract';
+export * from './input-normalizer';
+export * from './intent-classifier';
+export * from './context-retriever';
+export * from './prompt-compiler';
+export * from './cognition-planner';
+export * from './memory-settler';
+export * from './action-executor';
+export * from './experience-emitter';
+export * from './response-envelope';
+export * from './session-history';
+export * from './schema-validator';
+export * from './siduri-db';
+export * from './database';
+export * from './container';
+export * from './perception-pipeline';
+import { EvidenceRecord } from './evidence';
+import { ActionIntent } from './action';
+import { RequestContext } from './context';
+import { EarIngestOptions } from './ear-types';
+import { ClaimType, ClaimAuthority, ClaimStatus, DirectiveStatus, SourceEvent, MemoryProposal, BehaviorProposal } from './proposals';
+export interface OrganConfig {
+    provider: string;
+    [key: string]: unknown;
+}
+export interface CompanionConfig {
+    id: string;
+    name: string;
+    brain: OrganConfig;
+    voice: OrganConfig;
+    memory: OrganConfig;
+    knowledge: OrganConfig;
+    behavior: OrganConfig;
+    body: OrganConfig;
+    vision: OrganConfig;
+}
+export interface Message {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    name?: string;
+}
+export interface BrainContext {
+    systemPrompt: string;
+    contextPrompt: string;
+    recentMessages: Message[];
+    recipient?: MemoryScope;
+}
+export interface ResponsePlan {
+    speech: string;
+    language: string;
+    subtitle?: string;
+    subtitles?: Record<string, string>;
+    memoryProposals?: MemoryProposal[];
+    behaviorProposals?: BehaviorProposal[];
+    actionIntents?: ActionIntent[];
+    internalMonologue?: string;
+}
+export interface RetrievalPlan {
+    shouldQueryKnowledge: boolean;
+    knowledgeQueries: string[];
+    shouldQueryMemory?: boolean;
+    memoryQueries?: string[];
+    reasoning?: string;
+}
+export interface PersonaCompilationResult {
+    isValid: boolean;
+    manifest: {
+        specVersion?: string;
+        kind?: 'self';
+        id?: string;
+        name?: string;
+        version?: string;
+        author?: {
+            name: string;
+            url?: string;
+            signature?: string;
+        };
+        identity: {
+            name: string;
+            archetype?: string;
+            origin?: string;
+            ethos?: string;
+        };
+        personality?: PersonalityTraits;
+        relationships?: Array<{
+            entityId: string;
+            role?: string;
+            stance?: string;
+            conventions?: string[];
+        }>;
+        directives: Array<{
+            id?: string;
+            directive: string;
+            category?: 'guardrail' | 'relational' | 'behavioral';
+            priority?: number;
+            scopeActor?: string;
+            supersedesId?: string;
+        }>;
+        dialogueExamples?: Array<{
+            user: string;
+            assistant: string;
+        }>;
+    };
+    errors?: string[];
+}
+export interface BrainOrgan {
+    generatePlan(context: BrainContext): Promise<ResponsePlan>;
+    planRetrieval?(text: string, context?: RequestContext, recentHistory?: {
+        role: string;
+        content: string;
+    }[]): Promise<RetrievalPlan>;
+    compilePersona?(content: string, options?: {
+        companionId?: string;
+    }): Promise<PersonaCompilationResult>;
+}
+export type MemoryScope = 'companion' | 'user' | string;
+export interface Claim {
+    id: string;
+    subject: string;
+    predicate: string;
+    value: string;
+    status: ClaimStatus;
+    evidence?: string[];
+    scope?: MemoryScope;
+    companionId: string;
+    provenance?: string;
+    sourceEventId?: string;
+    claimType?: ClaimType;
+    authority?: ClaimAuthority;
+    userConfirmation?: 'explicit' | 'implied' | 'none';
+    sensitivity?: string;
+    confidence?: number;
+    assertedAt?: string;
+    validFrom?: string;
+    validUntil?: string;
+    supersedes?: string;
+    replaces?: string;
+    [key: string]: unknown;
+}
+export interface BehaviorDirective {
+    id: string;
+    companionId: string;
+    directive: string;
+    priority: number;
+    status: DirectiveStatus;
+    supersedesId?: string;
+    memoryClass?: 'identity' | 'relationship' | 'behavioral';
+    subject?: string;
+    predicate?: string;
+    value?: string;
+    validFrom?: string;
+    validUntil?: string;
+    [key: string]: unknown;
+}
+export interface MemoryQueryOptions {
+    sensitivity?: string;
+    limit?: number;
+    minConfidence?: number;
+    now?: string | Date;
+    [key: string]: unknown;
+}
+export interface MemoryOrgan {
+    initialize(companionId: string): Promise<void>;
+    proposeClaim(claim: Omit<Claim, 'id' | 'status' | 'companionId'>): Promise<Claim>;
+    searchClaims(query: string, scopeOrOptions?: MemoryScope | MemoryQueryOptions, limit?: number): Promise<Claim[]>;
+    getClaims(limit?: number): Promise<Claim[]>;
+    getPendingClaims(limit?: number): Promise<Claim[]>;
+    getApprovedClaims?(companionId?: string, limit?: number): Promise<any[]>;
+    approveClaim(id: string): Promise<void>;
+    rejectClaim(id: string): Promise<void>;
+    markClaimSessionOnly?(id: string): Promise<void>;
+    expireClaim?(id: string): Promise<void>;
+    revokeClaim?(id: string, reason?: string): Promise<void>;
+    getDirectives(companionId?: string): Promise<BehaviorDirective[]>;
+    proposeDirective(directiveData: Omit<BehaviorDirective, 'id' | 'status' | 'companionId'> & {
+        companionId?: string;
+    }): Promise<BehaviorDirective>;
+    approveDirective(id: string, companionId?: string): Promise<void>;
+    rejectDirective(id: string, companionId?: string): Promise<void>;
+    revokeDirective(id: string, companionId?: string): Promise<void>;
+    disableDirective(id: string, companionId?: string): Promise<void>;
+    expireDirective?(id: string, companionId?: string): Promise<void>;
+    supersedeClaim?(id: string, replacement: Omit<Claim, 'id' | 'status' | 'companionId'>): Promise<Claim>;
+    updateClaim?(id: string, updates: Partial<Pick<Claim, 'subject' | 'predicate' | 'value' | 'scope' | 'sensitivity' | 'confidence' | 'validFrom' | 'validUntil'>>): Promise<Claim>;
+    resetMemory?(): Promise<void>;
+    addSourceEvent?(event: SourceEvent): Promise<SourceEvent>;
+    getSourceEvent?(id: string): Promise<SourceEvent | undefined>;
+}
+export interface AudioEvent {
+    type: 'STARTED' | 'COMPLETED' | 'FAILED';
+    speechId: string;
+    text?: string;
+    language?: string;
+    audioBuffer?: Uint8Array;
+}
+export interface VoiceOrgan {
+    enqueueSpeech(text: string, language: string, priority?: number): string;
+    onLifecycleEvent(callback: (event: AudioEvent) => void): void;
+    getQueueStatus(): {
+        pending: number;
+        current?: string;
+    };
+}
+export interface VisionOrgan {
+    analyze(imageUrl: string, prompt: string): Promise<string>;
+}
+export interface ActiveSelfProjection {
+    identityFacts: string[];
+    relationshipFacts: string[];
+    behavioralRules: string[];
+    activeIds: string[];
+    excludedIds: string[];
+    diagnostics: Record<string, string>;
+    render(): string;
+}
+export interface BehaviorContext {
+    directives: BehaviorDirective[];
+    companionId?: string;
+    actorId?: string;
+    sessionId?: string;
+    now?: string;
+    [key: string]: unknown;
+}
+export interface BehaviorOrgan {
+    compile(context: BehaviorContext): Promise<string>;
+    compileProjection?(context: BehaviorContext): Promise<ActiveSelfProjection>;
+}
+export interface KnowledgeItem {
+    content: string;
+    provenance: string;
+    revision: string;
+    citations: KnowledgeCitation[];
+    evidenceRecord?: EvidenceRecord;
+}
+export interface KnowledgeCitation {
+    sourceId: string;
+    documentId?: string;
+    chunkId?: string;
+    locator?: string;
+}
+export interface KnowledgeOrgan {
+    search(query: string): Promise<KnowledgeItem[]>;
+}
+export interface EarPerception {
+    id: string;
+    source: string;
+    text?: string;
+    audioBuffer?: Uint8Array;
+    metadata?: Record<string, unknown>;
+    timestamp: string;
+}
+export interface EarOrgan {
+    listen(source: string, payload: unknown, options?: EarIngestOptions): Promise<EarPerception>;
+    transcribeAudio?(audio: Uint8Array): Promise<string>;
+    classifyIntent?(text: string, context?: RequestContext): Promise<Record<string, unknown>> | Record<string, unknown>;
+}
+export interface BodyOrgan {
+    setExpression(expression: string): void;
+    speak(speechId: string, text?: string, language?: string): void;
+    act(action: string): void;
+    completeAction?(): void;
+}
+export interface ObservationReading {
+    entity: string;
+    value: string;
+    confidence: number;
+    sourceCrop?: string;
+    ocrText?: string;
+    competingInterpretations?: string[];
+}
+export interface Observation {
+    observationId: string;
+    evidenceId: string;
+    sourceName: string;
+    providerId: string;
+    readings: ObservationReading[];
+    confidence: number;
+    createdAt: string;
+    expiresAt: string;
+    frameDigest: string;
+}
+export interface ObservationResult {
+    observation?: Observation;
+    duplicate: boolean;
+    reason?: 'empty_frame' | 'duplicate_frame' | 'invalid_reading' | 'provider_failure';
+}
+export interface ObservationOrgan {
+    ingest(frame: Uint8Array, sourceName: string, providerId?: string): Promise<ObservationResult>;
+    current(now?: Date): Observation[];
+    clearExpired(now?: Date): number;
+}
+export interface HealthProbeContext {
+    config: unknown;
+    env: NodeJS.ProcessEnv | Record<string, string | undefined>;
+}
+export interface HealthProbeResult {
+    ok: boolean;
+    message?: string;
+    details?: Record<string, unknown>;
+}
+export type HealthProbeFn = (context: HealthProbeContext) => Promise<HealthProbeResult> | HealthProbeResult;
+export * from './mouth-types';
+import type { SelfIdentity, PersonalityTraits, SelfDirective, SelfRelationship, SelfDialogueExample, LifeInventoryItem, LifeScheduleItem, LifePreference, LifeEntity, LifeEvent, LifeTask, MemoryClaim, EpisodicEvent } from './siduri-db';
+export type { SelfIdentity, PersonalityTraits, SelfDirective, SelfRelationship, SelfDialogueExample, LifeInventoryItem, LifeScheduleItem, LifePreference, LifeEntity, LifeEvent, LifeTask, MemoryClaim, EpisodicEvent, };
+export interface SelfRepository {
+    getIdentity(companionId: string): Promise<SelfIdentity | undefined>;
+    setIdentity(identity: SelfIdentity): Promise<void>;
+    getPersonality?(companionId: string): Promise<PersonalityTraits>;
+    setPersonality?(companionId: string, traits: PersonalityTraits): Promise<void>;
+    getActiveDirectives(companionId: string): Promise<SelfDirective[]>;
+    getRelationship(companionId: string, entityId: string): Promise<SelfRelationship | null>;
+    getRelationships?(companionId: string): Promise<SelfRelationship[]>;
+    getExemplars?(companionId: string): Promise<SelfDialogueExample[]>;
+    setExemplars?(companionId: string, exemplars: SelfDialogueExample[]): Promise<void>;
+    commitDirectives(companionId: string, directives: SelfDirective[]): Promise<void>;
+    updateRelationship(companionId: string, rel: SelfRelationship): Promise<void>;
+    disableDirective?(id: string, companionId?: string): Promise<void>;
+    approveDirective?(id: string, companionId?: string): Promise<void>;
+    rejectDirective?(id: string, companionId?: string): Promise<void>;
+    revokeDirective?(id: string, companionId?: string): Promise<void>;
+    expireDirective?(id: string, companionId?: string): Promise<void>;
+    getActiveSelf?(companionId: string): Promise<{
+        identity?: SelfIdentity;
+        personality?: PersonalityTraits;
+        directives: SelfDirective[];
+        relationships?: SelfRelationship[];
+        exemplars?: SelfDialogueExample[];
+    }>;
+}
+export interface LifeDatabase {
+    getInventory(companionId: string, domain?: string): Promise<LifeInventoryItem[]>;
+    getFinanceSummary?(companionId: string): Promise<any>;
+    getSchedule?(companionId: string, windowStart?: Date, windowEnd?: Date): Promise<LifeScheduleItem[]>;
+    getPreferences?(companionId: string): Promise<Record<string, string> | LifePreference[]>;
+    getEntities?(companionId: string, entityType?: string, domain?: string): Promise<LifeEntity[]>;
+    getEvents?(companionId: string, stream?: string, limit?: number): Promise<LifeEvent[]>;
+    getTasks?(companionId: string, status?: string): Promise<LifeTask[]>;
+    queryContext(companionId: string, query: string): Promise<string[]>;
+    searchLifeContext?(queryText: string): Promise<string[]>;
+}
+export interface EpisodicMemoryStore {
+    recordEvent(companionId: string, event: any): Promise<void>;
+    searchClaims(companionId: string, query: string, limit?: number): Promise<MemoryClaim[]>;
+    proposeClaim(claim: any): Promise<MemoryClaim>;
+    approveClaim(claimId: string): Promise<void>;
+    rejectClaim?(claimId: string): Promise<void>;
+    getApprovedClaims?(companionId: string, limit?: number): Promise<MemoryClaim[]>;
+    getRecentEvents?(companionId: string, limit?: number): Promise<EpisodicEvent[]>;
+}
+export interface EKnowledgeOrgan {
+    search(query: string): Promise<KnowledgeItem[]>;
+}
+export { promoteApprovedClaimToSelf, promoteApprovedClaimToKnowledge, isSelfAffectingClaim, isKnowledgeAffectingClaim, } from './runtime';
+export { SiduriDatabase, type SiduriDatabaseOptions, type LogLevel, type SystemLog, } from './siduri-db';

package/dist/index.js

@@ -0,0 +1,56 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SiduriDatabase = exports.isKnowledgeAffectingClaim = exports.isSelfAffectingClaim = exports.promoteApprovedClaimToKnowledge = exports.promoteApprovedClaimToSelf = void 0;
+// Export neutral context types and validator
+__exportStar(require("./context"), exports);
+__exportStar(require("./proposals"), exports);
+__exportStar(require("./evidence"), exports);
+__exportStar(require("./gating"), exports);
+__exportStar(require("./experience"), exports);
+__exportStar(require("./dispatcher"), exports);
+__exportStar(require("./action"), exports);
+__exportStar(require("./action-policy"), exports);
+__exportStar(require("./ear-types"), exports);
+__exportStar(require("./capability"), exports);
+__exportStar(require("./sqlite-action-store"), exports);
+__exportStar(require("./teaching"), exports);
+__exportStar(require("./runtime"), exports);
+__exportStar(require("./chat-contract"), exports);
+__exportStar(require("./input-normalizer"), exports);
+__exportStar(require("./intent-classifier"), exports);
+__exportStar(require("./context-retriever"), exports);
+__exportStar(require("./prompt-compiler"), exports);
+__exportStar(require("./cognition-planner"), exports);
+__exportStar(require("./memory-settler"), exports);
+__exportStar(require("./action-executor"), exports);
+__exportStar(require("./experience-emitter"), exports);
+__exportStar(require("./response-envelope"), exports);
+__exportStar(require("./session-history"), exports);
+__exportStar(require("./schema-validator"), exports);
+__exportStar(require("./siduri-db"), exports);
+__exportStar(require("./database"), exports);
+__exportStar(require("./container"), exports);
+__exportStar(require("./perception-pipeline"), exports);
+// Mouth (Communication & Output Delivery)
+__exportStar(require("./mouth-types"), exports);
+var runtime_1 = require("./runtime");
+Object.defineProperty(exports, "promoteApprovedClaimToSelf", { enumerable: true, get: function () { return runtime_1.promoteApprovedClaimToSelf; } });
+Object.defineProperty(exports, "promoteApprovedClaimToKnowledge", { enumerable: true, get: function () { return runtime_1.promoteApprovedClaimToKnowledge; } });
+Object.defineProperty(exports, "isSelfAffectingClaim", { enumerable: true, get: function () { return runtime_1.isSelfAffectingClaim; } });
+Object.defineProperty(exports, "isKnowledgeAffectingClaim", { enumerable: true, get: function () { return runtime_1.isKnowledgeAffectingClaim; } });
+var siduri_db_1 = require("./siduri-db");
+Object.defineProperty(exports, "SiduriDatabase", { enumerable: true, get: function () { return siduri_db_1.SiduriDatabase; } });

package/dist/input-normalizer.d.ts

@@ -0,0 +1,14 @@
+import { Message, RequestContext, EarOrgan } from './index';
+export interface NormalizedInput {
+    perceivedText: string;
+    sanitizedText: string;
+    requestContext: RequestContext;
+    role: 'OWNER' | 'VIEWER' | 'OPERATOR';
+    isContextObject: boolean;
+    boundedHistory: Message[];
+}
+/**
+ * Validates raw user input, synthesizes RequestContext, normalizes history,
+ * and routes input through EarOrgan if available.
+ */
+export declare function normalizeUserInput(message: string, roleOrContext: ("OWNER" | "VIEWER" | "OPERATOR" | RequestContext | string) | undefined, history: Message[] | undefined, companionId: string, ear?: EarOrgan): Promise<NormalizedInput>;

package/dist/input-normalizer.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeUserInput = normalizeUserInput;
+/**
+ * Validates raw user input, synthesizes RequestContext, normalizes history,
+ * and routes input through EarOrgan if available.
+ */
+async function normalizeUserInput(message, roleOrContext = 'OWNER', history = [], companionId, ear) {
+    if (typeof message !== 'string' || !message.trim() || message.length > 4000) {
+        throw new Error('message must be a non-empty string of at most 4000 characters');
+    }
+    if (!Array.isArray(history) ||
+        history.length > 20 ||
+        history.some((item) => !item || !['user', 'assistant'].includes(item.role) || typeof item.content !== 'string')) {
+        throw new Error('history must contain at most 20 user/assistant messages');
+    }
+    const isContextObject = typeof roleOrContext === 'object' && roleOrContext !== null;
+    const role = isContextObject
+        ? (roleOrContext.actor?.authorizationRole === 'viewer' || roleOrContext.actor?.authenticated === false
+            ? 'VIEWER'
+            : 'OWNER')
+        : roleOrContext;
+    const defaultActor = {
+        actorId: role === 'VIEWER' ? 'anonymous-session' : 'owner-user',
+        sessionId: `sess-${companionId}`,
+        authorizationRole: role === 'VIEWER' ? 'viewer' : 'administrator',
+        capabilities: role === 'VIEWER' ? ['chat'] : ['chat', 'memory:approve', 'action:execute'],
+        authenticated: role !== 'VIEWER',
+    };
+    const defaultConversation = {
+        channel: 'direct',
+        correlationId: `corr-${Date.now()}`,
+    };
+    const requestContext = isContextObject
+        ? {
+            companionId: roleOrContext.companionId || companionId,
+            actor: {
+                ...defaultActor,
+                ...(roleOrContext.actor || {}),
+            },
+            conversation: {
+                ...defaultConversation,
+                ...(roleOrContext.conversation || {}),
+            },
+            source: roleOrContext.source || 'local',
+            ...(roleOrContext.mode ? { mode: roleOrContext.mode } : {}),
+            ...(roleOrContext.subject ? { subject: roleOrContext.subject } : {}),
+            ...(roleOrContext.metadata ? { metadata: roleOrContext.metadata } : {}),
+        }
+        : {
+            companionId,
+            actor: defaultActor,
+            conversation: defaultConversation,
+            source: 'local',
+        };
+    // Universal Perception: Route user input through EarOrgan if available
+    let perceivedText = message;
+    if (ear && typeof ear.listen === 'function') {
+        const perception = await ear.listen('text_chat', message, {
+            context: requestContext,
+        });
+        perceivedText = perception.text || message;
+    }
+    const boundedHistory = history.map((item) => ({
+        role: item.role,
+        content: item.content.slice(0, 2000).replace(/\0/g, ''),
+    }));
+    return {
+        perceivedText,
+        sanitizedText: message,
+        requestContext,
+        role,
+        isContextObject,
+        boundedHistory,
+    };
+}

package/dist/input-normalizer.test.d.ts

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

package/dist/input-normalizer.test.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const input_normalizer_1 = require("./input-normalizer");
+describe('InputNormalizer', () => {
+    test('rejects empty or oversized messages', async () => {
+        await expect((0, input_normalizer_1.normalizeUserInput)('', 'OWNER', [], 'comp-1')).rejects.toThrow('message must be a non-empty string of at most 4000 characters');
+        await expect((0, input_normalizer_1.normalizeUserInput)('   ', 'OWNER', [], 'comp-1')).rejects.toThrow('message must be a non-empty string of at most 4000 characters');
+        const oversized = 'a'.repeat(4001);
+        await expect((0, input_normalizer_1.normalizeUserInput)(oversized, 'OWNER', [], 'comp-1')).rejects.toThrow('message must be a non-empty string of at most 4000 characters');
+    });
+    test('rejects oversized history or invalid message roles', async () => {
+        const invalidHistory = Array(21).fill({ role: 'user', content: 'hi' });
+        await expect((0, input_normalizer_1.normalizeUserInput)('hi', 'OWNER', invalidHistory, 'comp-1')).rejects.toThrow('history must contain at most 20 user/assistant messages');
+        const malformedRole = [{ role: 'bad_role', content: 'test' }];
+        await expect((0, input_normalizer_1.normalizeUserInput)('hi', 'OWNER', malformedRole, 'comp-1')).rejects.toThrow('history must contain at most 20 user/assistant messages');
+    });
+    test('normalizes role string into full RequestContext and strips null bytes from history', async () => {
+        const historyWithNulls = [{ role: 'user', content: 'hello\0world' }];
+        const result = await (0, input_normalizer_1.normalizeUserInput)('hello', 'OWNER', historyWithNulls, 'comp-1');
+        expect(result.role).toBe('OWNER');
+        expect(result.requestContext.companionId).toBe('comp-1');
+        expect(result.requestContext.actor.authorizationRole).toBe('administrator');
+        expect(result.requestContext.actor.authenticated).toBe(true);
+        expect(result.boundedHistory[0].content).toBe('helloworld');
+    });
+    test('routes input through EarOrgan when present', async () => {
+        const mockEar = {
+            listen: jest.fn().mockResolvedValue({
+                id: 'perc-1',
+                source: 'text_chat',
+                text: 'transcribed text',
+                timestamp: new Date().toISOString(),
+            }),
+        };
+        const result = await (0, input_normalizer_1.normalizeUserInput)('raw text', 'VIEWER', [], 'comp-1', mockEar);
+        expect(mockEar.listen).toHaveBeenCalledWith('text_chat', 'raw text', expect.anything());
+        expect(result.perceivedText).toBe('transcribed text');
+    });
+    test('safely normalizes partial context object (e.g. { mode: "hybrid" }) with default actor and conversation', async () => {
+        const result = await (0, input_normalizer_1.normalizeUserInput)('test query', { mode: 'hybrid' }, [], 'comp-2');
+        expect(result.requestContext.conversation).toBeDefined();
+        expect(result.requestContext.conversation.channel).toBe('direct');
+        expect(result.requestContext.conversation.correlationId).toBeDefined();
+        expect(result.requestContext.actor).toBeDefined();
+        expect(result.requestContext.actor.actorId).toBe('owner-user');
+        expect(result.requestContext.mode).toBe('hybrid');
+    });
+});

package/dist/intent-classifier.d.ts

@@ -0,0 +1,37 @@
+import { RequestContext, InteractionMode } from './index';
+import { extractDeterministicTeaching } from './teaching';
+export interface IntentClassification {
+    normalizedMessage: string;
+    explicitTeaching: ReturnType<typeof extractDeterministicTeaching>;
+    isTeachingLike: boolean;
+    isSelfIdentityRequest: boolean;
+    isGreeting: boolean;
+    shouldQueryKnowledge: boolean;
+    knowledgeQueries?: string[];
+    primaryQuery?: string;
+    memoryQueries?: string[];
+    effectiveMode: InteractionMode;
+    confidence?: number;
+    classifierOrigin?: 'heuristic' | 'cognitive' | 'ear' | 'brain';
+}
+export type CognitiveIntentClassifier = (text: string, context: RequestContext) => Promise<Partial<IntentClassification>> | Partial<IntentClassification>;
+/**
+ * Strips conversational syntax, companion invocations, and question carrier phrases
+ * to extract targeted keyword search terms (e.g., "Siduri, who is Sandrone" -> ["Sandrone"]).
+ */
+export declare function extractSearchKeywords(text: string, companionName?: string, recentHistory?: {
+    role: string;
+    content: string;
+}[]): string[];
+/**
+ * Evaluates domain heuristics and intent classification for user messages.
+ * Determines if deterministic teaching is present, resolves the effective
+ * interaction mode (casual, teach, hybrid), and determines if external knowledge
+ * retrieval is appropriate.
+ */
+export declare function classifyInputIntent(text: string, context: RequestContext, overrides?: Partial<IntentClassification>): IntentClassification;
+/**
+ * Asynchronously classifies intent, allowing an EarOrgan or cognitive model
+ * to provide semantic classification before falling back to heuristics.
+ */
+export declare function classifyInputIntentAsync(text: string, context: RequestContext, classifier?: CognitiveIntentClassifier): Promise<IntentClassification>;