@backbay/glia 0.2.0-alpha.1

package/dist/emotion/micro-expressions.js

@@ -0,0 +1,75 @@
+// packages/bb-ui/src/emotion/micro-expressions.ts
+/**
+ * Simple seeded pseudo-random number generator
+ */
+function seededRandom(seed) {
+    let state = seed;
+    return () => {
+        state = (state * 1103515245 + 12345) & 0x7fffffff;
+        return state / 0x7fffffff;
+    };
+}
+/**
+ * Create a smooth noise generator (Perlin-like)
+ * Returns values between -1 and 1
+ */
+export function createNoiseGenerator(seed = 42) {
+    const rand = seededRandom(seed);
+    // Pre-generate gradient table
+    const gradients = [];
+    for (let i = 0; i < 256; i++) {
+        gradients.push(rand() * 2 - 1);
+    }
+    // Smoothstep interpolation
+    const smoothstep = (t) => t * t * (3 - 2 * t);
+    return (t) => {
+        const i0 = Math.floor(t) & 255;
+        const i1 = (i0 + 1) & 255;
+        const frac = t - Math.floor(t);
+        const g0 = gradients[i0];
+        const g1 = gradients[i1];
+        const d0 = g0 * frac;
+        const d1 = g1 * (frac - 1);
+        return smoothstep(frac) * (d1 - d0) + d0;
+    };
+}
+// Global noise generators for each dimension (different seeds)
+const arousalNoise = createNoiseGenerator(42);
+const valenceNoise = createNoiseGenerator(137);
+const opennessNoise = createNoiseGenerator(256);
+/**
+ * Apply micro-expression variations to base AVO state
+ */
+export function applyMicroExpression(base, config, time) {
+    if (!config.enabled) {
+        return base;
+    }
+    const t = time * config.frequency;
+    // Apply noise scaled by config amplitude
+    const noiseA = arousalNoise(t) * config.arousalNoise;
+    const noiseV = valenceNoise(t + 100) * config.valenceNoise;
+    const noiseO = opennessNoise(t + 200) * config.opennessNoise;
+    // Clamp to valid 0-1 range
+    return {
+        arousal: Math.max(0, Math.min(1, base.arousal + noiseA)),
+        valence: Math.max(0, Math.min(1, base.valence + noiseV)),
+        openness: Math.max(0, Math.min(1, base.openness + noiseO)),
+    };
+}
+/**
+ * Create a micro-expression animator that tracks time internally
+ */
+export function createMicroExpressionAnimator(config) {
+    let time = 0;
+    return {
+        tick(deltaMs) {
+            time += deltaMs / 1000;
+        },
+        apply(base) {
+            return applyMicroExpression(base, config, time);
+        },
+        reset() {
+            time = 0;
+        },
+    };
+}

package/dist/emotion/transitions.d.ts

@@ -0,0 +1,29 @@
+import type { AVO, EasingFunction, TransitionOptions } from './types.js';
+/**
+ * Easing functions
+ */
+export declare const EASING_FUNCTIONS: Record<EasingFunction, (t: number) => number>;
+/**
+ * Apply easing function to progress value (clamped 0-1)
+ */
+export declare function ease(fn: EasingFunction, t: number): number;
+/**
+ * Calculate appropriate transition duration based on AVO change
+ * Returns duration in milliseconds
+ * - Urgent (200ms) for sudden negative changes (e.g., error states)
+ * - Recovery uses longer duration with distance factor
+ * - Default: proportional to AVO distance
+ */
+export declare function getTransitionDuration(from: AVO, to: AVO): number;
+/**
+ * Get recommended easing for a transition based on emotional context
+ * - Urgent negative: fast out (easeOut)
+ * - Recovery: springy for natural bounce-back
+ * - Default: smooth in-out
+ */
+export declare function getTransitionEasing(from: AVO, to: AVO): EasingFunction;
+/**
+ * Get complete transition config with duration, easing, and onComplete callback
+ */
+export declare function getTransitionConfig(from: AVO, to: AVO): Required<TransitionOptions>;
+//# sourceMappingURL=transitions.d.ts.map

package/dist/emotion/transitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.d.ts","sourceRoot":"","sources":["../../src/emotion/transitions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,GAAG,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGzE;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAU1E,CAAC;AAEF;;GAEG;AACH,wBAAgB,IAAI,CAAC,EAAE,EAAE,cAAc,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,GAAG,MAAM,CAiBhE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,GAAG,cAAc,CAgBtE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,GAAG,QAAQ,CAAC,iBAAiB,CAAC,CAMnF"}

package/dist/emotion/transitions.js

@@ -0,0 +1,74 @@
+// packages/bb-ui/src/emotion/transitions.ts
+import { avoDistance } from './mapping.js';
+/**
+ * Easing functions
+ */
+export const EASING_FUNCTIONS = {
+    linear: (t) => t,
+    easeIn: (t) => t * t,
+    easeOut: (t) => 1 - Math.pow(1 - t, 2),
+    easeInOut: (t) => t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2,
+    spring: (t) => {
+        const c4 = (2 * Math.PI) / 3;
+        return t === 0 ? 0 : t === 1 ? 1 :
+            Math.pow(2, -10 * t) * Math.sin((t * 10 - 0.75) * c4) + 1;
+    },
+};
+/**
+ * Apply easing function to progress value (clamped 0-1)
+ */
+export function ease(fn, t) {
+    return EASING_FUNCTIONS[fn](Math.max(0, Math.min(1, t)));
+}
+/**
+ * Calculate appropriate transition duration based on AVO change
+ * Returns duration in milliseconds
+ * - Urgent (200ms) for sudden negative changes (e.g., error states)
+ * - Recovery uses longer duration with distance factor
+ * - Default: proportional to AVO distance
+ */
+export function getTransitionDuration(from, to) {
+    const distance = avoDistance(from, to);
+    const valenceDrop = from.valence - to.valence;
+    const arousalSpike = to.arousal - from.arousal;
+    // Urgent: sudden negative change (error state)
+    if (valenceDrop > 0.3 && arousalSpike > 0.2) {
+        return 200;
+    }
+    // Recovery: returning to positive
+    if (to.valence > from.valence && to.valence > 0.6) {
+        return 600 + distance * 400;
+    }
+    // Default: proportional to distance
+    return Math.floor(200 + distance * 800);
+}
+/**
+ * Get recommended easing for a transition based on emotional context
+ * - Urgent negative: fast out (easeOut)
+ * - Recovery: springy for natural bounce-back
+ * - Default: smooth in-out
+ */
+export function getTransitionEasing(from, to) {
+    const valenceDrop = from.valence - to.valence;
+    const arousalSpike = to.arousal - from.arousal;
+    // Urgent negative: fast out
+    if (valenceDrop > 0.3 && arousalSpike > 0.2) {
+        return 'easeOut';
+    }
+    // Recovery: springy
+    if (to.valence > from.valence && to.valence > 0.7) {
+        return 'spring';
+    }
+    // Default
+    return 'easeInOut';
+}
+/**
+ * Get complete transition config with duration, easing, and onComplete callback
+ */
+export function getTransitionConfig(from, to) {
+    return {
+        duration: getTransitionDuration(from, to),
+        easing: getTransitionEasing(from, to),
+        onComplete: () => { },
+    };
+}

package/dist/emotion/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Glyph Emotion System Types
+ *
+ * AVO dimensional model based on Russell's Circumplex Model of Affect
+ */
+/**
+ * The three emotional dimensions (all 0-1 range)
+ */
+export interface AVODimensions {
+    /** Arousal: 0 (dormant) to 1 (intense) - energy/activation level */
+    arousal: number;
+    /** Valence: 0 (distressed) to 1 (elated) - positivity/confidence */
+    valence: number;
+    /** Openness: 0 (receptive) to 1 (expressive) - input/output direction */
+    openness: number;
+}
+/** Shorthand alias */
+export type AVO = AVODimensions;
+/**
+ * Named anchor states - recognizable emotional configurations
+ */
+export type AnchorState = 'dormant' | 'idle' | 'attentive' | 'curious' | 'listening' | 'thinking' | 'contemplating' | 'focused' | 'responding' | 'explaining' | 'enthusiastic' | 'satisfied' | 'proud' | 'uncertain' | 'concerned' | 'struggling' | 'alarmed' | 'error' | 'recovering' | 'relieved';
+/**
+ * Easing function types for transitions
+ */
+export type EasingFunction = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | 'spring';
+/**
+ * Transition configuration
+ */
+export interface TransitionOptions {
+    /** Duration in milliseconds */
+    duration?: number;
+    /** Easing function */
+    easing?: EasingFunction;
+    /** Callback when transition completes */
+    onComplete?: () => void;
+}
+/**
+ * Visual state derived from AVO dimensions
+ */
+export interface VisualState {
+    breathingRate: number;
+    breathingAmplitude: number;
+    ringRotationSpeed: number;
+    particleVelocity: number;
+    particleCount: number;
+    glowPulseRate: number;
+    coreHue: number;
+    coreSaturation: number;
+    motionNoise: number;
+    scaleFactor: number;
+    emissiveIntensity: number;
+    particleFlowDirection: number;
+    particleSpreadAngle: number;
+    breathingPhaseBias: number;
+    ringTilt: number;
+    auraExpansion: number;
+    overallIntensity: number;
+}
+/**
+ * Emotion events that can trigger state changes
+ */
+export interface EmotionEvent {
+    type: 'input_received' | 'processing_start' | 'processing_complete' | 'error_occurred' | 'success' | 'user_idle' | 'interrupt';
+    /** Intensity of the event (0-1) */
+    intensity?: number;
+    /** Additional event data */
+    data?: unknown;
+}
+/**
+ * Micro-expression configuration for natural movement
+ */
+export interface MicroExpressionConfig {
+    enabled: boolean;
+    arousalNoise: number;
+    valenceNoise: number;
+    opennessNoise: number;
+    frequency: number;
+}
+/**
+ * Legacy GlyphState for backward compatibility
+ */
+export type LegacyGlyphState = 'idle' | 'listening' | 'thinking' | 'responding' | 'success' | 'error' | 'sleep';
+//# sourceMappingURL=types.d.ts.map

package/dist/emotion/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/emotion/types.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,sBAAsB;AACtB,MAAM,MAAM,GAAG,GAAG,aAAa,CAAC;AAEhC;;GAEG;AACH,MAAM,MAAM,WAAW,GAEnB,SAAS,GACT,MAAM,GAEN,WAAW,GACX,SAAS,GACT,WAAW,GAEX,UAAU,GACV,eAAe,GACf,SAAS,GAET,YAAY,GACZ,YAAY,GACZ,cAAc,GAEd,WAAW,GACX,OAAO,GAEP,WAAW,GACX,WAAW,GACX,YAAY,GACZ,SAAS,GACT,OAAO,GAEP,YAAY,GACZ,UAAU,CAAC;AAEf;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,WAAW,GACX,QAAQ,CAAC;AAEb;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAE1B,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IAGtB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAG1B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IAGtB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EACA,gBAAgB,GAChB,kBAAkB,GAClB,qBAAqB,GACrB,gBAAgB,GAChB,SAAS,GACT,WAAW,GACX,WAAW,CAAC;IAChB,mCAAmC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,WAAW,GACX,UAAU,GACV,YAAY,GACZ,SAAS,GACT,OAAO,GACP,OAAO,CAAC"}

package/dist/emotion/types.js

@@ -0,0 +1,2 @@
+// packages/bb-ui/src/emotion/types.ts
+export {};

package/dist/hooks/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * bb-ui hooks
+ */
+export { useSync, type UseSyncOptions, type UseSyncReturn } from './useSync.js';
+export { useAgentRun, type UseAgentRunOptions, type UseAgentRunReturn } from './useAgentRun.js';
+export { useRunStream, subscribeToRunEvents, type UseRunStreamOptions, type UseRunStreamReturn, } from './useRunStream.js';
+export { useIntensity, IntensityProvider, useIntensityContext, type UseIntensityOptions, type UseIntensityReturn, type IntensityProviderProps, } from './useIntensity.js';
+export { usePlaySession, type UsePlaySessionOptions, type UsePlaySessionReturn, } from './usePlaySession.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAEhF,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEhG,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,GAC5B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC"}

package/dist/hooks/index.js

@@ -0,0 +1,8 @@
+/**
+ * bb-ui hooks
+ */
+export { useSync } from './useSync.js';
+export { useAgentRun } from './useAgentRun.js';
+export { useRunStream, subscribeToRunEvents, } from './useRunStream.js';
+export { useIntensity, IntensityProvider, useIntensityContext, } from './useIntensity.js';
+export { usePlaySession, } from './usePlaySession.js';

package/dist/hooks/useAgentRun.d.ts

@@ -0,0 +1,36 @@
+/**
+ * useAgentRun - Hook for executing agent runs
+ */
+import type { AgentRun, RunStatus } from '../protocol/types.js';
+export interface UseAgentRunOptions {
+    /** Called when run starts */
+    onStart?: (run: AgentRun) => void;
+    /** Called when run completes */
+    onComplete?: (run: AgentRun) => void;
+    /** Called when run fails */
+    onError?: (run: AgentRun, error: Error) => void;
+    /** Called when run is cancelled */
+    onCancel?: (run: AgentRun) => void;
+}
+export interface UseAgentRunReturn {
+    /** Current run object or null */
+    run: AgentRun | null;
+    /** Current status */
+    status: RunStatus;
+    /** Run output when completed */
+    output: string | null;
+    /** Error message if failed */
+    error: string | null;
+    /** Actual cost incurred */
+    cost: number | null;
+    /** Time taken in ms */
+    latency: number | null;
+    /** Start a new run */
+    start: (agentId: string, prompt: string, context?: Record<string, unknown>) => Promise<void>;
+    /** Cancel the current run */
+    cancel: () => void;
+    /** Whether a run is in progress */
+    isRunning: boolean;
+}
+export declare function useAgentRun(options?: UseAgentRunOptions): UseAgentRunReturn;
+//# sourceMappingURL=useAgentRun.d.ts.map

package/dist/hooks/useAgentRun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAgentRun.d.ts","sourceRoot":"","sources":["../../src/hooks/useAgentRun.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAOhE,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,CAAC;IAElC,gCAAgC;IAChC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,CAAC;IAErC,4BAA4B;IAC5B,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAEhD,mCAAmC;IACnC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAErB,qBAAqB;IACrB,MAAM,EAAE,SAAS,CAAC;IAElB,gCAAgC;IAChC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAErB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAEpB,uBAAuB;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEvB,sBAAsB;IACtB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7F,6BAA6B;IAC7B,MAAM,EAAE,MAAM,IAAI,CAAC;IAEnB,mCAAmC;IACnC,SAAS,EAAE,OAAO,CAAC;CACpB;AAMD,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,iBAAiB,CAyJ/E"}

package/dist/hooks/useAgentRun.js

@@ -0,0 +1,140 @@
+/**
+ * useAgentRun - Hook for executing agent runs
+ */
+import { useState, useCallback, useRef } from 'react';
+import { useBBContext } from '../components/BBProvider.js';
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+export function useAgentRun(options = {}) {
+    const { onStart, onComplete, onError, onCancel } = options;
+    const { config, addRun, updateRun, getAgent } = useBBContext();
+    const [run, setRun] = useState(null);
+    const [status, setStatus] = useState('idle');
+    const [output, setOutput] = useState(null);
+    const [error, setError] = useState(null);
+    const [cost, setCost] = useState(null);
+    const [latency, setLatency] = useState(null);
+    const abortControllerRef = useRef(null);
+    const start = useCallback(async (agentId, prompt, context) => {
+        // Cancel any existing run
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+        }
+        const controller = new AbortController();
+        abortControllerRef.current = controller;
+        const runId = `run-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+        const startedAt = Date.now();
+        const newRun = {
+            id: runId,
+            agentId,
+            prompt,
+            context,
+            status: 'running',
+            startedAt,
+        };
+        // Update state
+        setRun(newRun);
+        setStatus('running');
+        setOutput(null);
+        setError(null);
+        setCost(null);
+        setLatency(null);
+        // Add to global tracking
+        addRun(newRun);
+        onStart?.(newRun);
+        try {
+            // Make API call
+            const response = await fetch(`${config.apiBaseUrl}/runs`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...config.headers,
+                },
+                body: JSON.stringify({
+                    agentId,
+                    prompt,
+                    context,
+                }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            const result = await response.json();
+            const completedAt = Date.now();
+            const runLatency = completedAt - startedAt;
+            // Get agent cost estimate
+            const agent = getAgent(agentId);
+            const runCost = result.cost ?? agent?.costPerRun ?? 0;
+            const completedRun = {
+                ...newRun,
+                status: 'completed',
+                output: result.output,
+                cost: runCost,
+                tokenCount: result.tokenCount,
+                latencyMs: runLatency,
+                completedAt,
+            };
+            // Update state
+            setRun(completedRun);
+            setStatus('completed');
+            setOutput(result.output);
+            setCost(runCost);
+            setLatency(runLatency);
+            // Update global tracking
+            updateRun(runId, completedRun);
+            onComplete?.(completedRun);
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                // Cancelled
+                const cancelledRun = {
+                    ...newRun,
+                    status: 'cancelled',
+                    completedAt: Date.now(),
+                };
+                setRun(cancelledRun);
+                setStatus('cancelled');
+                updateRun(runId, cancelledRun);
+                onCancel?.(cancelledRun);
+                return;
+            }
+            // Failed
+            const errorMessage = err instanceof Error ? err.message : 'Unknown error';
+            const failedRun = {
+                ...newRun,
+                status: 'failed',
+                error: errorMessage,
+                completedAt: Date.now(),
+            };
+            setRun(failedRun);
+            setStatus('failed');
+            setError(errorMessage);
+            updateRun(runId, failedRun);
+            onError?.(failedRun, err instanceof Error ? err : new Error(errorMessage));
+        }
+        finally {
+            if (abortControllerRef.current === controller) {
+                abortControllerRef.current = null;
+            }
+        }
+    }, [config, addRun, updateRun, getAgent, onStart, onComplete, onError, onCancel]);
+    const cancel = useCallback(() => {
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+            abortControllerRef.current = null;
+        }
+    }, []);
+    return {
+        run,
+        status,
+        output,
+        error,
+        cost,
+        latency,
+        start,
+        cancel,
+        isRunning: status === 'running',
+    };
+}

package/dist/hooks/useIntensity.d.ts

@@ -0,0 +1,33 @@
+/**
+ * useIntensity - Hook for tracking agent activity intensity
+ *
+ * Provides semantic visual feedback based on agent activity levels.
+ */
+import type { IntensityValues } from '../protocol/types.js';
+export interface UseIntensityOptions {
+    /** Smoothing factor for transitions (0-1, lower = smoother) */
+    smoothing?: number;
+    /** Update interval in ms */
+    updateInterval?: number;
+    /** Sources to track */
+    sources?: Array<'activeRuns' | 'pendingSync' | 'custom'>;
+    /** Custom intensity source (0-1) */
+    customIntensity?: number;
+}
+export interface UseIntensityReturn extends IntensityValues {
+    /** Set custom intensity value */
+    setCustomIntensity: (value: number) => void;
+    /** CSS custom properties object for inline styles */
+    cssVars: Record<string, string>;
+    /** Get CSS custom properties as a string for style attribute */
+    cssVarsString: string;
+}
+export declare function useIntensity(options?: UseIntensityOptions): UseIntensityReturn;
+import { type ReactNode } from 'react';
+export interface IntensityProviderProps {
+    children: ReactNode;
+    options?: UseIntensityOptions;
+}
+export declare function IntensityProvider({ children, options }: IntensityProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useIntensityContext(): IntensityValues;
+//# sourceMappingURL=useIntensity.d.ts.map

package/dist/hooks/useIntensity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIntensity.d.ts","sourceRoot":"","sources":["../../src/hooks/useIntensity.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAO5D,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,4BAA4B;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,uBAAuB;IACvB,OAAO,CAAC,EAAE,KAAK,CAAC,YAAY,GAAG,aAAa,GAAG,QAAQ,CAAC,CAAC;IAEzD,oCAAoC;IACpC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,iCAAiC;IACjC,kBAAkB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAE5C,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhC,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;CACvB;AAaD,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,kBAAkB,CA0HlF;AAMD,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAIlE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,SAAS,CAAC;IACpB,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B;AAED,wBAAgB,iBAAiB,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,sBAAsB,2CAiB9E;AAED,wBAAgB,mBAAmB,IAAI,eAAe,CAMrD"}

package/dist/hooks/useIntensity.js

@@ -0,0 +1,128 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * useIntensity - Hook for tracking agent activity intensity
+ *
+ * Provides semantic visual feedback based on agent activity levels.
+ */
+import { useState, useEffect, useMemo, useCallback, useRef } from 'react';
+import { useBBContext } from '../components/BBProvider.js';
+// =============================================================================
+// Constants
+// =============================================================================
+const DEFAULT_SMOOTHING = 0.3;
+const DEFAULT_UPDATE_INTERVAL = 50;
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+export function useIntensity(options = {}) {
+    const { smoothing = DEFAULT_SMOOTHING, updateInterval = DEFAULT_UPDATE_INTERVAL, sources = ['activeRuns'], customIntensity: initialCustom = 0, } = options;
+    const { activeRuns, syncStatus } = useBBContext();
+    const [customIntensity, setCustomIntensity] = useState(initialCustom);
+    const [values, setValues] = useState({
+        intensity: 0,
+        presence: 0,
+        activity: 0,
+        breathing: 0,
+    });
+    // Refs for smooth animation
+    const targetRef = useRef({
+        intensity: 0,
+        presence: 0,
+        activity: 0,
+        breathing: 0,
+    });
+    const animationFrameRef = useRef(null);
+    const lastUpdateRef = useRef(Date.now());
+    // Calculate target intensity from sources
+    const calculateTarget = useCallback(() => {
+        let runIntensity = 0;
+        let syncIntensity = 0;
+        let custom = 0;
+        if (sources.includes('activeRuns')) {
+            runIntensity = Math.min(activeRuns.length / 3, 1); // Max at 3 concurrent runs
+        }
+        if (sources.includes('pendingSync')) {
+            syncIntensity = syncStatus === 'pending' ? 0.5 : syncStatus === 'conflict' ? 0.8 : 0;
+        }
+        if (sources.includes('custom')) {
+            custom = customIntensity;
+        }
+        // Combine sources
+        const combinedIntensity = Math.min(Math.max(runIntensity, syncIntensity, custom), 1);
+        // Calculate derived values
+        const presence = combinedIntensity > 0 ? Math.min(combinedIntensity + 0.3, 1) : 0;
+        const activity = combinedIntensity;
+        const breathing = combinedIntensity > 0.2 ? Math.min(combinedIntensity * 1.2, 1) : 0;
+        targetRef.current = {
+            intensity: combinedIntensity,
+            presence,
+            activity,
+            breathing,
+        };
+    }, [activeRuns.length, syncStatus, customIntensity, sources]);
+    // Smooth animation loop
+    useEffect(() => {
+        const animate = () => {
+            const now = Date.now();
+            const delta = (now - lastUpdateRef.current) / 1000;
+            lastUpdateRef.current = now;
+            // Recalculate target
+            calculateTarget();
+            // Lerp toward target
+            const lerpFactor = 1 - Math.pow(1 - smoothing, delta * 60);
+            setValues((prev) => ({
+                intensity: prev.intensity + (targetRef.current.intensity - prev.intensity) * lerpFactor,
+                presence: prev.presence + (targetRef.current.presence - prev.presence) * lerpFactor,
+                activity: prev.activity + (targetRef.current.activity - prev.activity) * lerpFactor,
+                breathing: prev.breathing + (targetRef.current.breathing - prev.breathing) * lerpFactor,
+            }));
+            animationFrameRef.current = requestAnimationFrame(animate);
+        };
+        animationFrameRef.current = requestAnimationFrame(animate);
+        return () => {
+            if (animationFrameRef.current) {
+                cancelAnimationFrame(animationFrameRef.current);
+            }
+        };
+    }, [calculateTarget, smoothing]);
+    // CSS custom properties
+    const cssVars = useMemo(() => ({
+        '--bb-intensity': values.intensity.toFixed(3),
+        '--bb-intensity-presence': values.presence.toFixed(3),
+        '--bb-intensity-activity': values.activity.toFixed(3),
+        '--bb-intensity-breathing': values.breathing.toFixed(3),
+    }), [values]);
+    const cssVarsString = useMemo(() => Object.entries(cssVars)
+        .map(([key, value]) => `${key}: ${value}`)
+        .join('; '), [cssVars]);
+    return {
+        ...values,
+        setCustomIntensity,
+        cssVars,
+        cssVarsString,
+    };
+}
+// =============================================================================
+// Provider Component (optional)
+// =============================================================================
+import { createContext, useContext } from 'react';
+const IntensityContext = createContext(null);
+export function IntensityProvider({ children, options }) {
+    const intensity = useIntensity(options);
+    // Apply CSS vars to document root
+    useEffect(() => {
+        const root = document.documentElement;
+        root.style.setProperty('--bb-intensity', intensity.intensity.toFixed(3));
+        root.style.setProperty('--bb-intensity-presence', intensity.presence.toFixed(3));
+        root.style.setProperty('--bb-intensity-activity', intensity.activity.toFixed(3));
+        root.style.setProperty('--bb-intensity-breathing', intensity.breathing.toFixed(3));
+    }, [intensity]);
+    return (_jsx(IntensityContext.Provider, { value: intensity, children: children }));
+}
+export function useIntensityContext() {
+    const context = useContext(IntensityContext);
+    if (!context) {
+        throw new Error('useIntensityContext must be used within an IntensityProvider');
+    }
+    return context;
+}