@backbay/glia 0.2.0-alpha.1

package/dist/cognition/hooks/useCognition.js

@@ -0,0 +1,88 @@
+'use client';
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { CognitionController } from '../controller.js';
+/**
+ * React hook for managing Glyph cognition state.
+ *
+ * Creates a CognitionController and provides reactive state updates.
+ * Automatically handles RAF-based animation when autoTick is true (default).
+ *
+ * @example
+ * ```tsx
+ * const { state, emotion, emit, tick } = useCognition({
+ *   initial: { mode: 'idle' },
+ *   onChange: (state) => console.log('Cognition changed:', state),
+ * });
+ *
+ * // Handle agent events
+ * emit({ type: 'run.started', runId: 'r1' });
+ *
+ * // Access emotion bridge for rendering
+ * console.log(emotion.anchor, emotion.avo);
+ * ```
+ */
+export function useCognition(options = {}) {
+    const { initial, onChange, autoTick = true } = options;
+    // Create controller ref (stable across renders)
+    const controllerRef = useRef(null);
+    if (!controllerRef.current) {
+        controllerRef.current = new CognitionController({ initial });
+    }
+    const controller = controllerRef.current;
+    // State for React reactivity
+    const [state, setState] = useState(controller.getState());
+    const [emotion, setEmotion] = useState(controller.getEmotionTarget());
+    // Store onChange in ref to avoid effect dependency changes
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+    // Subscribe to controller events
+    useEffect(() => {
+        const unsub = controller.on('change', (newState) => {
+            setState({ ...newState });
+            setEmotion(controller.getEmotionTarget());
+            onChangeRef.current?.(newState);
+        });
+        return () => {
+            unsub();
+        };
+    }, [controller]);
+    // Auto-tick with RAF
+    useEffect(() => {
+        if (!autoTick)
+            return;
+        let lastTime = performance.now();
+        let rafId;
+        const tickFn = (time) => {
+            const delta = time - lastTime;
+            lastTime = time;
+            controller.tick(delta);
+            rafId = requestAnimationFrame(tickFn);
+        };
+        rafId = requestAnimationFrame(tickFn);
+        return () => {
+            cancelAnimationFrame(rafId);
+        };
+    }, [controller, autoTick]);
+    // Cleanup on unmount
+    useEffect(() => {
+        return () => {
+            controller.dispose();
+        };
+    }, [controller]);
+    // Stable callbacks
+    const handleEvent = useCallback((event) => {
+        controller.handleEvent(event);
+    }, [controller]);
+    const tick = useCallback((deltaMs) => {
+        controller.tick(deltaMs);
+    }, [controller]);
+    // Deprecated alias for backwards compatibility
+    const emit = handleEvent;
+    return {
+        state,
+        emotion,
+        handleEvent,
+        tick,
+        emit,
+    };
+}

package/dist/cognition/index.d.ts

@@ -0,0 +1,10 @@
+export type { CognitiveMode, CognitiveSubmode, CognitionSignals, PersonaSignals, TrapWarning, DetailedBalance, DynamicsState, PersonalityConfig, PolicyConfig, EvidenceRef, CognitionState, CognitionEvent, CognitionSnapshot, } from './types.js';
+export { clamp01, createInitialCognitionState } from './types.js';
+export { CognitionStateSchema, CognitionSnapshotSchema, validateCognitionSnapshot, } from './schema.js';
+export type { CognitionSnapshotInput, CognitionSnapshotOutput, CognitionSnapshotValidationResult, } from './schema.js';
+export { reduceEvent, reduceDecay, MODE_TRANSITION_MAP } from './reducers.js';
+export { CognitionController } from './controller.js';
+export type { CognitionControllerOptions } from './controller.js';
+export { useCognition } from './hooks/index.js';
+export type { UseCognitionOptions, UseCognitionResult } from './hooks/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cognition/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cognition/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,OAAO,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAMlE,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,sBAAsB,EACtB,uBAAuB,EACvB,iCAAiC,GAClC,MAAM,aAAa,CAAC;AAMrB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAM9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,YAAY,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAMlE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/cognition/index.js

@@ -0,0 +1,20 @@
+// =============================================================================
+// Types
+// =============================================================================
+export { clamp01, createInitialCognitionState } from './types.js';
+// =============================================================================
+// Schema
+// =============================================================================
+export { CognitionStateSchema, CognitionSnapshotSchema, validateCognitionSnapshot, } from './schema.js';
+// =============================================================================
+// Reducers
+// =============================================================================
+export { reduceEvent, reduceDecay, MODE_TRANSITION_MAP } from './reducers.js';
+// =============================================================================
+// Controller
+// =============================================================================
+export { CognitionController } from './controller.js';
+// =============================================================================
+// Hooks
+// =============================================================================
+export { useCognition } from './hooks/index.js';

package/dist/cognition/reducers.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Cognition State Reducers
+ *
+ * Pure functions for updating cognition state based on events and time decay.
+ */
+import type { CognitionState, CognitionEvent, CognitiveMode } from './types.js';
+/**
+ * Trigger types that cause mode transitions
+ */
+export type CognitionTrigger = 'ui.input_received' | 'ui.user_idle' | 'ui.interrupt' | 'run.started' | 'run.completed' | 'run.event';
+/**
+ * Maps trigger events to resulting cognitive modes
+ */
+export declare const MODE_TRANSITION_MAP: Record<CognitionTrigger, CognitiveMode>;
+/**
+ * Decay rates per second for various signals
+ */
+export declare const DECAY_RATES: Record<'errorStress' | 'timePressure' | 'planDrift', number>;
+/**
+ * Apply exponential decay to time-based signals
+ */
+export declare function reduceDecay(state: CognitionState, deltaMs: number): CognitionState;
+/**
+ * Main event reducer - handles all cognition events
+ */
+export declare function reduceEvent(state: CognitionState, event: CognitionEvent): CognitionState;
+//# sourceMappingURL=reducers.d.ts.map

package/dist/cognition/reducers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reducers.d.ts","sourceRoot":"","sources":["../../src/cognition/reducers.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,aAAa,EAKd,MAAM,YAAY,CAAC;AAGpB;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,mBAAmB,GACnB,cAAc,GACd,cAAc,GACd,aAAa,GACb,eAAe,GACf,WAAW,CAAC;AAEhB;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,gBAAgB,EAAE,aAAa,CAOvE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,aAAa,GAAG,cAAc,GAAG,WAAW,EAAE,MAAM,CAIpF,CAAC;AA0FF;;GAEG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,MAAM,GACd,cAAc,CAoBhB;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,cAAc,GACpB,cAAc,CAqDhB"}

package/dist/cognition/reducers.js

@@ -0,0 +1,152 @@
+// packages/bb-ui/src/cognition/reducers.ts
+import { clamp01 } from './types.js';
+/**
+ * Maps trigger events to resulting cognitive modes
+ */
+export const MODE_TRANSITION_MAP = {
+    'ui.input_received': 'listening',
+    'ui.user_idle': 'idle',
+    'ui.interrupt': 'listening',
+    'run.started': 'deliberating',
+    'run.completed': 'idle',
+    'run.event': 'deliberating',
+};
+/**
+ * Decay rates per second for various signals
+ */
+export const DECAY_RATES = {
+    errorStress: 0.1, // Decays 10% per second
+    timePressure: 0.05, // Decays 5% per second
+    planDrift: 0.08, // Decays 8% per second
+};
+/**
+ * Reduce signals from a signals.update event
+ */
+function reduceSignals(state, signals) {
+    return {
+        ...state,
+        attention: signals.attention !== undefined ? clamp01(signals.attention) : state.attention,
+        workload: signals.workload !== undefined ? clamp01(signals.workload) : state.workload,
+        risk: signals.risk !== undefined ? clamp01(signals.risk) : state.risk,
+        timePressure: signals.timePressure !== undefined ? clamp01(signals.timePressure) : state.timePressure,
+        errorStress: signals.errorStress !== undefined ? clamp01(signals.errorStress) : state.errorStress,
+        planDrift: signals.planDrift !== undefined ? clamp01(signals.planDrift) : state.planDrift,
+        costPressure: signals.costPressure !== undefined ? clamp01(signals.costPressure) : state.costPressure,
+        uncertainty: signals.uncertainty !== undefined ? clamp01(signals.uncertainty) : state.uncertainty,
+        confidence: signals.confidence !== undefined ? clamp01(signals.confidence) : state.confidence,
+    };
+}
+/**
+ * Reduce dynamics state update
+ */
+function reduceDynamicsUpdate(state, dynamics) {
+    return {
+        ...state,
+        dynamics,
+    };
+}
+/**
+ * Reduce policy/personality update
+ */
+function reducePolicyUpdate(state, policy, personality) {
+    return {
+        ...state,
+        policy: policy ?? state.policy,
+        personality: personality ?? state.personality,
+    };
+}
+/**
+ * Reduce mode transitions based on events
+ */
+function reduceModeTransition(state, event) {
+    const trigger = event.type;
+    const newMode = MODE_TRANSITION_MAP[trigger];
+    if (!newMode) {
+        return state;
+    }
+    let focusRunId = state.focusRunId;
+    let errorStress = state.errorStress;
+    let mode = newMode;
+    // Handle run-related events
+    if (event.type === 'run.started') {
+        focusRunId = event.runId;
+    }
+    else if (event.type === 'run.completed') {
+        focusRunId = undefined;
+        if (!event.success) {
+            errorStress = clamp01(state.errorStress + 0.2);
+            mode = 'recovering';
+        }
+    }
+    else if (event.type === 'run.event') {
+        focusRunId = event.runId;
+    }
+    return {
+        ...state,
+        mode,
+        focusRunId,
+        errorStress,
+    };
+}
+/**
+ * Apply exponential decay to time-based signals
+ */
+export function reduceDecay(state, deltaMs) {
+    const deltaSec = deltaMs / 1000;
+    // Exponential decay: value * e^(-rate * time)
+    const errorStress = clamp01(state.errorStress * Math.exp(-DECAY_RATES.errorStress * deltaSec));
+    const timePressure = clamp01(state.timePressure * Math.exp(-DECAY_RATES.timePressure * deltaSec));
+    const planDrift = clamp01(state.planDrift * Math.exp(-DECAY_RATES.planDrift * deltaSec));
+    return {
+        ...state,
+        errorStress,
+        timePressure,
+        planDrift,
+    };
+}
+/**
+ * Main event reducer - handles all cognition events
+ */
+export function reduceEvent(state, event) {
+    switch (event.type) {
+        case 'signals.update':
+            return reduceSignals(state, event.signals);
+        case 'intensity.update':
+            return reduceSignals(state, event.values);
+        case 'dynamics.update':
+            return reduceDynamicsUpdate(state, event.dynamics);
+        case 'policy.update':
+            return reducePolicyUpdate(state, event.policy, event.personality);
+        case 'tick':
+            return reduceDecay(state, event.deltaMs);
+        case 'ui.input_received':
+        case 'ui.user_idle':
+        case 'ui.interrupt':
+        case 'run.started':
+        case 'run.completed':
+        case 'run.event':
+            return reduceModeTransition(state, event);
+        case 'text.user_message': {
+            // Text messages transition to listening mode and update persona drift risk
+            // based on message categories per spec section 7.5
+            const categories = event.categories ?? [];
+            const driftRisk = categories.includes('meta_reflection')
+                ? 0.3
+                : categories.includes('vulnerable_disclosure')
+                    ? 0.4
+                    : 0;
+            // Exponential smoothing: 70% previous, 30% new
+            const newPersonaDriftRisk = clamp01(state.personaDriftRisk * 0.7 + driftRisk * 0.3);
+            return {
+                ...state,
+                mode: 'listening',
+                personaDriftRisk: newPersonaDriftRisk,
+            };
+        }
+        default: {
+            // Exhaustive check - TypeScript will error if we miss a case
+            const _exhaustive = event;
+            return state;
+        }
+    }
+}