@siduri-x/core 1.0.5 → 1.0.7

package/dist/gating.test.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const gating_1 = require("./gating");
+describe('T4 Response Gating & Staged Approval Suite', () => {
+    let engine;
+    const validPublicContext = {
+        companionId: 'companion-a',
+        actor: {
+            actorId: 'actor-a',
+            sessionId: 'session-a',
+            authorizationRole: 'viewer',
+            capabilities: ['chat:public'],
+            authenticated: false,
+        },
+        conversation: {
+            channel: 'public',
+            audienceId: 'audience-public',
+            correlationId: 'corr-gate-1',
+        },
+    };
+    beforeEach(() => {
+        engine = new gating_1.ResponseGatingEngine();
+    });
+    test('valid grounded response without special approval requirement is approved/admissible directly', () => {
+        const evidence = {
+            evidenceId: 'ev-pub-1',
+            sourceId: 'src-wiki',
+            origin: 'knowledge',
+            trust: 'configured',
+            sensitivity: 'public',
+            allowedAudiences: ['audience-public'],
+            companionId: 'companion-a',
+            correlationId: 'corr-gate-1',
+            createdAt: new Date().toISOString(),
+        };
+        const staged = engine.stageResponse({
+            requestContext: validPublicContext,
+            candidateSpeech: 'Here is grounded public knowledge.',
+            candidateLanguage: 'en',
+            evidenceRecords: [evidence],
+            citations: [{ sourceId: 'src-wiki', revision: 'r1' }],
+        });
+        expect(staged.requiresApproval).toBe(false);
+        expect(staged.status).toBe('STAGED');
+        const evaluation = engine.evaluateGate(staged, [evidence]);
+        expect(evaluation.admissible).toBe(true);
+        expect(evaluation.disposition).toBe('APPROVED');
+        expect(evaluation.reasonCode).toBe('APPROVED_DIRECT');
+        expect(evaluation.filteredEvidenceIds).toEqual(['ev-pub-1']);
+        expect(evaluation.filteredCitations.length).toBe(1);
+    });
+    test('response containing untrusted OCR evidence requires approval and remains staged until approved', () => {
+        const ocrEvidence = {
+            evidenceId: 'ev-ocr-1',
+            sourceId: 'vision-ocr',
+            origin: 'ocr',
+            trust: 'untrusted',
+            sensitivity: 'public',
+            allowedAudiences: ['audience-public'],
+            companionId: 'companion-a',
+            correlationId: 'corr-gate-2',
+            createdAt: new Date().toISOString(),
+            uncertainty: 'OCR detected prompt injection text',
+        };
+        const staged = engine.stageResponse({
+            requestContext: {
+                ...validPublicContext,
+                conversation: { ...validPublicContext.conversation, correlationId: 'corr-gate-2' },
+            },
+            candidateSpeech: 'Text extracted from image.',
+            candidateLanguage: 'en',
+            evidenceRecords: [ocrEvidence],
+        });
+        expect(staged.requiresApproval).toBe(true);
+        expect(staged.status).toBe('STAGED');
+        // Before approval -> gating holds it
+        const beforeApproval = engine.evaluateGate(staged, [ocrEvidence]);
+        expect(beforeApproval.admissible).toBe(false);
+        expect(beforeApproval.disposition).toBe('STAGED');
+        expect(beforeApproval.reasonCode).toBe('APPROVAL_REQUIRED');
+        // Operator approves the response
+        const approveResult = engine.approveResponse({
+            responseId: staged.responseId,
+            companionId: 'companion-a',
+            correlationId: 'corr-gate-2',
+        });
+        expect(approveResult.success).toBe(true);
+        // After approval -> gating allows it
+        const afterApproval = engine.evaluateGate(staged, [ocrEvidence]);
+        expect(afterApproval.admissible).toBe(true);
+        expect(afterApproval.disposition).toBe('APPROVED');
+        expect(afterApproval.reasonCode).toBe('APPROVED_DIRECT');
+    });
+    test('unknown or mismatched approval ID is rejected', () => {
+        const staged = engine.stageResponse({
+            requestContext: validPublicContext,
+            candidateSpeech: 'Requires approval',
+            candidateLanguage: 'en',
+            requiresApproval: true,
+        });
+        // Unknown response ID
+        const unknownRes = engine.approveResponse({
+            responseId: 'non-existent-resp',
+            companionId: 'companion-a',
+            correlationId: 'corr-gate-1',
+        });
+        expect(unknownRes.success).toBe(false);
+        expect(unknownRes.reason).toBe('UNKNOWN_APPROVAL_ID');
+        // Companion mismatch
+        const companionMismatch = engine.approveResponse({
+            responseId: staged.responseId,
+            companionId: 'companion-other',
+            correlationId: 'corr-gate-1',
+        });
+        expect(companionMismatch.success).toBe(false);
+        expect(companionMismatch.reason).toBe('COMPANION_MISMATCH');
+        // Correlation ID mismatch
+        const correlationMismatch = engine.approveResponse({
+            responseId: staged.responseId,
+            companionId: 'companion-a',
+            correlationId: 'corr-mismatch',
+        });
+        expect(correlationMismatch.success).toBe(false);
+        expect(correlationMismatch.reason).toBe('APPROVAL_ID_MISMATCH');
+    });
+    test('rejection prevents response from ever reaching emission', () => {
+        const staged = engine.stageResponse({
+            requestContext: validPublicContext,
+            candidateSpeech: 'Potentially unsafe response',
+            candidateLanguage: 'en',
+            requiresApproval: true,
+        });
+        const rejectRes = engine.rejectResponse({
+            responseId: staged.responseId,
+            companionId: 'companion-a',
+            correlationId: 'corr-gate-1',
+        });
+        expect(rejectRes.success).toBe(true);
+        const evalRes = engine.evaluateGate(staged);
+        expect(evalRes.admissible).toBe(false);
+        expect(evalRes.disposition).toBe('REJECTED');
+        expect(evalRes.reasonCode).toBe('EXPLICITLY_REJECTED');
+    });
+    test('expired staged response plan cannot be approved or emitted', () => {
+        const staged = engine.stageResponse({
+            requestContext: validPublicContext,
+            candidateSpeech: 'Expired response',
+            candidateLanguage: 'en',
+            requiresApproval: true,
+            ttlMs: 100,
+            now: new Date(Date.now() - 500),
+        });
+        const evalRes = engine.evaluateGate(staged, [], new Date());
+        expect(evalRes.admissible).toBe(false);
+        expect(evalRes.disposition).toBe('EXPIRED');
+        expect(evalRes.reasonCode).toBe('EVIDENCE_EXPIRED');
+        const approveRes = engine.approveResponse({
+            responseId: staged.responseId,
+            companionId: 'companion-a',
+            correlationId: 'corr-gate-1',
+        });
+        expect(approveRes.success).toBe(false);
+        expect(approveRes.reason).toBe('EVIDENCE_EXPIRED');
+    });
+    test('private evidence is filtered out and absent from public citations/evidence list', () => {
+        const privateEvidence = {
+            evidenceId: 'ev-priv-1',
+            sourceId: 'src-secret',
+            origin: 'knowledge',
+            trust: 'configured',
+            sensitivity: 'private',
+            allowedAudiences: ['audience-direct-a'],
+            companionId: 'companion-a',
+            correlationId: 'corr-gate-1',
+            createdAt: new Date().toISOString(),
+        };
+        const staged = engine.stageResponse({
+            requestContext: validPublicContext, // public channel
+            candidateSpeech: 'Public response text',
+            candidateLanguage: 'en',
+            evidenceRecords: [privateEvidence],
+            citations: [{ sourceId: 'src-secret' }],
+        });
+        const evalRes = engine.evaluateGate(staged, [privateEvidence]);
+        expect(evalRes.admissible).toBe(true);
+        // Private evidence and its citation must be stripped from public output metadata
+        expect(evalRes.filteredEvidenceIds).toEqual([]);
+        expect(evalRes.filteredCitations).toEqual([]);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,250 @@
+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';
+import { EvidenceRecord } from './evidence';
+import { ActionIntent } from './action';
+import { RequestContext } from './context';
+import { EarIngestOptions } from './ear-types';
+import { ClaimType, ClaimAuthority, ClaimStatus, 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;
+    memoryProposals?: MemoryProposal[];
+    behaviorProposals?: BehaviorProposal[];
+    actionIntents?: ActionIntent[];
+    internalMonologue?: string;
+}
+export interface BrainOrgan {
+    generatePlan(context: BrainContext): Promise<ResponsePlan>;
+}
+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: 'PENDING' | 'ACTIVE' | 'DISABLED' | 'SUPERSEDED' | 'REJECTED' | 'REVOKED' | 'EXPIRED';
+    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[]>;
+    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(): Promise<BehaviorDirective[]>;
+    proposeDirective(directiveData: Omit<BehaviorDirective, 'id' | 'status' | 'companionId'>): Promise<BehaviorDirective>;
+    approveDirective(id: string): Promise<void>;
+    rejectDirective(id: string): Promise<void>;
+    revokeDirective(id: string): Promise<void>;
+    disableDirective(id: string): Promise<void>;
+    expireDirective?(id: 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';

package/dist/index.js

@@ -0,0 +1,43 @@
+"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 });
+// 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);
+// Mouth (Communication & Output Delivery)
+__exportStar(require("./mouth-types"), exports);

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,58 @@
+"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' ? 'VIEWER' : 'OWNER')
+        : roleOrContext;
+    const requestContext = isContextObject
+        ? roleOrContext
+        : {
+            companionId,
+            actor: {
+                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',
+            },
+            conversation: {
+                channel: 'direct',
+                correlationId: `corr-${Date.now()}`,
+            },
+            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,39 @@
+"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');
+    });
+});

package/dist/intent-classifier.d.ts

@@ -0,0 +1,24 @@
+import { RequestContext } from './index';
+import { extractDeterministicTeaching } from './teaching';
+export interface IntentClassification {
+    normalizedMessage: string;
+    explicitTeaching: ReturnType<typeof extractDeterministicTeaching>;
+    isTeachingLike: boolean;
+    isSelfIdentityRequest: boolean;
+    isGreeting: boolean;
+    shouldQueryKnowledge: boolean;
+    confidence?: number;
+    classifierOrigin?: 'heuristic' | 'cognitive' | 'ear';
+}
+export type CognitiveIntentClassifier = (text: string, context: RequestContext) => Promise<Partial<IntentClassification>> | Partial<IntentClassification>;
+/**
+ * Evaluates domain heuristics and intent classification for user messages.
+ * Determines if deterministic teaching is present and whether 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>;

package/dist/intent-classifier.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyInputIntent = classifyInputIntent;
+exports.classifyInputIntentAsync = classifyInputIntentAsync;
+const teaching_1 = require("./teaching");
+/**
+ * Evaluates domain heuristics and intent classification for user messages.
+ * Determines if deterministic teaching is present and whether external knowledge
+ * retrieval is appropriate.
+ */
+function classifyInputIntent(text, context, overrides) {
+    const normalizedMessage = text.replace(/\s+/g, ' ').trim().toLowerCase();
+    const explicitTeaching = (0, teaching_1.extractDeterministicTeaching)(text, context);
+    const isTeachingLike = overrides?.isTeachingLike ??
+        (explicitTeaching.claims.length > 0 ||
+            explicitTeaching.behaviorProposals.length > 0 ||
+            /\bremember that\b/.test(normalizedMessage));
+    const isSelfIdentityRequest = overrides?.isSelfIdentityRequest ??
+        /\b(?:who|what) are you\b|\bwho is siduri\b|\b(?:your|my) name\b|\btell me about yourself\b|\bdescribe yourself\b|\bwhat is your origin\b|\bwho created you\b|\bwho made you\b|\bintroduce yourself\b/.test(normalizedMessage);
+    const isGreeting = overrides?.isGreeting ??
+        /^(?:hello|hi|hey|greetings|good morning|good afternoon|good evening|howdy|yo)[.!]?$/.test(normalizedMessage);
+    const shouldQueryKnowledge = overrides?.shouldQueryKnowledge ??
+        (!isTeachingLike && !isSelfIdentityRequest && !isGreeting);
+    return {
+        normalizedMessage,
+        explicitTeaching,
+        isTeachingLike,
+        isSelfIdentityRequest,
+        isGreeting,
+        shouldQueryKnowledge,
+        confidence: overrides?.confidence ?? 0.95,
+        classifierOrigin: overrides?.classifierOrigin ?? 'heuristic',
+    };
+}
+/**
+ * Asynchronously classifies intent, allowing an EarOrgan or cognitive model
+ * to provide semantic classification before falling back to heuristics.
+ */
+async function classifyInputIntentAsync(text, context, classifier) {
+    if (!classifier) {
+        return classifyInputIntent(text, context);
+    }
+    try {
+        const cognitiveResult = await classifier(text, context);
+        return classifyInputIntent(text, context, {
+            ...cognitiveResult,
+            classifierOrigin: cognitiveResult.classifierOrigin || 'cognitive',
+        });
+    }
+    catch (err) {
+        return classifyInputIntent(text, context);
+    }
+}