@fenixforce/edition-mobile 0.1.0

package/dist/lib/sync/client.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Sync Client — bidirectional sync between Mobile (client) and Pro (server).
+ * Protocol: GET /sync/status → POST /sync/push → GET /sync/pull?since= → POST /sync/ack
+ * Conflicts: higher syncVersion wins. Ties broken by most recent updatedAt.
+ */
+import type { SQLiteDB } from "../storage/sqlite-adapter.js";
+export interface SyncStatus {
+    lastSync: string;
+    pendingLocal: number;
+    pendingRemote: number;
+    connected: boolean;
+}
+export interface MemoryFact {
+    id: string;
+    content: string;
+    category: string;
+    confidence: number;
+    syncVersion: number;
+    updatedAt: string;
+}
+export interface SyncMessage {
+    id: string;
+    conversationId: string;
+    role: string;
+    content: string;
+    syncVersion: number;
+    createdAt: string;
+}
+export interface IdentityPush {
+    fileName: string;
+    content: string;
+    updatedAt: string;
+}
+export interface LocalChanges {
+    facts: MemoryFact[];
+    messages: SyncMessage[];
+    identity?: IdentityPush[];
+}
+export interface PushResult {
+    accepted: number;
+    conflicts: ConflictRecord[];
+    serverTime: string;
+}
+export interface PullResult {
+    facts: MemoryFact[];
+    messages: SyncMessage[];
+    identity: IdentityPush[];
+    serverTime: string;
+}
+export interface ConflictRecord {
+    entityType: "fact" | "message" | "identity";
+    entityId: string;
+    localVersion: number;
+    remoteVersion: number;
+    localUpdatedAt: string;
+    remoteUpdatedAt: string;
+    resolvedTo: "local" | "remote";
+}
+export interface SyncClient {
+    status(): Promise<SyncStatus>;
+    push(changes: LocalChanges): Promise<PushResult>;
+    pull(since: string): Promise<PullResult>;
+    ack(receivedUpTo: string): Promise<void>;
+    fullSync(): Promise<{
+        pushed: PushResult;
+        pulled: PullResult;
+    }>;
+}
+export interface SyncClientConfig {
+    /** Base URL of the Pro server (e.g. https://fenix.example.com). */
+    serverUrl: string;
+    /** Bearer token for authentication (stored in expo-secure-store). */
+    authToken: string;
+    /** SQLite database handle for reading local changes and storing conflicts. */
+    db: SQLiteDB;
+    /** Override fetch for testing. */
+    fetchFn?: typeof globalThis.fetch;
+    /** Maximum retries on network failure. */
+    maxRetries?: number;
+}
+export declare function createSyncClient(config: SyncClientConfig): SyncClient;

package/dist/lib/sync/triggers.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Sync Triggers — manages when sync runs. Sync does not run continuously.
+ *
+ * Trigger points:
+ * 1. App foreground — check status, sync if pending
+ * 2. Post-conversation — after 5 min inactivity or chat close
+ * 3. Manual — user taps "Sync Now"
+ * 4. Background — periodic via expo-task-manager (30 min, WiFi + charging)
+ * 5. Push notification — silent push from Pro triggers pull
+ *
+ * Each trigger checks connectivity before attempting sync.
+ * Failed syncs are retried on the next trigger (no exponential backoff
+ * since triggers are already infrequent).
+ */
+import type { SyncClient } from "./client.js";
+export type TriggerSource = "foreground" | "post_conversation" | "manual" | "background" | "push";
+export interface SyncTriggerConfig {
+    syncClient: SyncClient;
+    isOnline: () => boolean;
+    /** Post-conversation debounce interval in ms. Default 5 minutes. */
+    debounceMs?: number;
+    /** Background sync interval in ms. Default 30 minutes. */
+    backgroundIntervalMs?: number;
+    /** Called before sync starts. Return false to cancel. */
+    onSyncStart?: (source: TriggerSource) => boolean | void;
+    /** Called after sync completes or fails. */
+    onSyncEnd?: (source: TriggerSource, result: SyncResult) => void;
+    /** Register the background task. Null in test environments. */
+    registerBackgroundTask?: (taskName: string, intervalMs: number) => Promise<void>;
+    /** Unregister the background task. */
+    unregisterBackgroundTask?: (taskName: string) => Promise<void>;
+}
+export interface SyncResult {
+    success: boolean;
+    source: TriggerSource;
+    pushed?: number;
+    pulled?: number;
+    error?: string;
+}
+export interface SyncTriggers {
+    /** Fire when app comes to foreground. */
+    onForeground(): Promise<SyncResult>;
+    /** Fire when a conversation ends or goes idle. Debounced. */
+    onConversationIdle(): void;
+    /** Fire for manual "Sync Now" from settings. */
+    syncNow(): Promise<SyncResult>;
+    /** Fire from silent push notification. */
+    onPushNotification(): Promise<SyncResult>;
+    /** Register background task. Call once at boot. */
+    registerBackground(): Promise<void>;
+    /** Unregister background task. Call on teardown. */
+    unregisterBackground(): Promise<void>;
+    /** Execute the sync cycle (used by background task runner). */
+    executeSync(source: TriggerSource): Promise<SyncResult>;
+    /** Cancel any pending debounce timer. */
+    dispose(): void;
+}
+export declare const SYNC_TASK_NAME = "fenix-background-sync";
+export declare function createSyncTriggers(config: SyncTriggerConfig): SyncTriggers;

package/dist/lib/tools/calendar.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Calendar tool adapter — wraps expo-calendar for the kernel's ToolHandler.
+ * Requests permission on first use, not at app launch.
+ */
+export interface CalendarAdapter {
+    requestPermissions(): Promise<{
+        status: string;
+    }>;
+    getCalendarsAsync(): Promise<Array<{
+        id: string;
+        title: string;
+    }>>;
+    getEventsAsync(calendarIds: string[], startDate: Date, endDate: Date): Promise<CalendarEvent[]>;
+    createEventAsync(calendarId: string, details: Record<string, unknown>): Promise<string>;
+}
+export interface CalendarEvent {
+    id: string;
+    title: string;
+    startDate: string;
+    endDate: string;
+    location?: string;
+    notes?: string;
+}
+export declare function createCalendarTool(calendar: CalendarAdapter): {
+    name: "device.calendar";
+    description: string;
+    parameters: {
+        action: {
+            type: "string";
+            description: string;
+            required: boolean;
+        };
+        startDate: {
+            type: "string";
+            description: string;
+        };
+        endDate: {
+            type: "string";
+            description: string;
+        };
+        title: {
+            type: "string";
+            description: string;
+        };
+        location: {
+            type: "string";
+            description: string;
+        };
+        query: {
+            type: "string";
+            description: string;
+        };
+    };
+    handler: (params: Record<string, unknown>) => Promise<{
+        error: string;
+        events?: undefined;
+        created?: undefined;
+        eventId?: undefined;
+    } | {
+        events: {
+            id: string;
+            title: string;
+            start: string;
+            end: string;
+            location: string | undefined;
+        }[];
+        error?: undefined;
+        created?: undefined;
+        eventId?: undefined;
+    } | {
+        created: boolean;
+        eventId: string;
+        error?: undefined;
+        events?: undefined;
+    }>;
+};

package/dist/lib/tools/camera.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Camera tool adapter — wraps expo-camera for the kernel's ToolHandler.
+ */
+export interface CameraAdapter {
+    requestCameraPermissions(): Promise<{
+        status: string;
+    }>;
+    takePicture(): Promise<{
+        uri: string;
+        width: number;
+        height: number;
+    }>;
+    pickImage(): Promise<{
+        uri: string;
+        width: number;
+        height: number;
+    } | null>;
+}
+export declare function createCameraTool(camera: CameraAdapter): {
+    name: "device.camera";
+    description: string;
+    parameters: {
+        action: {
+            type: "string";
+            description: string;
+            required: boolean;
+        };
+    };
+    handler: (params: Record<string, unknown>) => Promise<{
+        error: string;
+        uri?: undefined;
+        width?: undefined;
+        height?: undefined;
+    } | {
+        uri: string;
+        width: number;
+        height: number;
+        error?: undefined;
+    }>;
+};

package/dist/lib/tools/contacts.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Contacts tool adapter — wraps expo-contacts for the kernel's ToolHandler.
+ */
+export interface ContactsAdapter {
+    requestPermissions(): Promise<{
+        status: string;
+    }>;
+    getContactsAsync(opts: {
+        fields: string[];
+        pageSize?: number;
+    }): Promise<{
+        data: Contact[];
+    }>;
+}
+export interface Contact {
+    id: string;
+    name?: string;
+    firstName?: string;
+    lastName?: string;
+    phoneNumbers?: Array<{
+        number: string;
+        label?: string;
+    }>;
+    emails?: Array<{
+        email: string;
+        label?: string;
+    }>;
+}
+export declare function createContactsTool(contacts: ContactsAdapter): {
+    name: "device.contacts";
+    description: string;
+    parameters: {
+        action: {
+            type: "string";
+            description: string;
+            required: boolean;
+        };
+        query: {
+            type: "string";
+            description: string;
+        };
+        limit: {
+            type: "number";
+            description: string;
+        };
+    };
+    handler: (params: Record<string, unknown>) => Promise<{
+        error: string;
+        contacts?: undefined;
+    } | {
+        contacts: {
+            id: string;
+            name: string;
+            phone: string | null;
+            email: string | null;
+        }[];
+        error?: undefined;
+    }>;
+};

package/dist/lib/tools/location.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Location tool adapter — wraps expo-location for the kernel's ToolHandler.
+ */
+export interface LocationAdapter {
+    requestForegroundPermissions(): Promise<{
+        status: string;
+    }>;
+    getCurrentPosition(): Promise<{
+        coords: {
+            latitude: number;
+            longitude: number;
+            altitude: number | null;
+        };
+    }>;
+    reverseGeocode(lat: number, lng: number): Promise<Array<{
+        city: string | null;
+        region: string | null;
+        country: string | null;
+        street: string | null;
+    }>>;
+}
+export declare function createLocationTool(location: LocationAdapter): {
+    name: "device.location";
+    description: string;
+    parameters: {
+        action: {
+            type: "string";
+            description: string;
+            required: boolean;
+        };
+        latitude: {
+            type: "number";
+            description: string;
+        };
+        longitude: {
+            type: "number";
+            description: string;
+        };
+    };
+    handler: (params: Record<string, unknown>) => Promise<{
+        city: string | null;
+        region: string | null;
+        country: string | null;
+        street: string | null;
+    } | {
+        error: string;
+        latitude?: undefined;
+        longitude?: undefined;
+        altitude?: undefined;
+        address?: undefined;
+    } | {
+        latitude: number;
+        longitude: number;
+        altitude: number | null;
+        address: string | null;
+        error?: undefined;
+    }>;
+};

package/dist/lib/tools/notifications.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Notifications tool adapter — wraps expo-notifications for the kernel's ToolHandler.
+ */
+export interface NotificationsAdapter {
+    requestPermissions(): Promise<{
+        status: string;
+    }>;
+    scheduleNotification(content: {
+        title: string;
+        body: string;
+        data?: Record<string, unknown>;
+    }, trigger: {
+        seconds: number;
+    } | null): Promise<string>;
+    cancelNotification(id: string): Promise<void>;
+    getPendingNotifications(): Promise<Array<{
+        identifier: string;
+        content: {
+            title: string;
+            body: string;
+        };
+    }>>;
+}
+export declare function createNotificationsTool(notifications: NotificationsAdapter): {
+    name: "device.notifications";
+    description: string;
+    parameters: {
+        action: {
+            type: "string";
+            description: string;
+            required: boolean;
+        };
+        title: {
+            type: "string";
+            description: string;
+        };
+        body: {
+            type: "string";
+            description: string;
+        };
+        delaySeconds: {
+            type: "number";
+            description: string;
+        };
+        notificationId: {
+            type: "string";
+            description: string;
+        };
+    };
+    handler: (params: Record<string, unknown>) => Promise<{
+        error: string;
+        scheduled?: undefined;
+        notificationId?: undefined;
+        notifications?: undefined;
+        cancelled?: undefined;
+    } | {
+        scheduled: boolean;
+        notificationId: string;
+        error?: undefined;
+        notifications?: undefined;
+        cancelled?: undefined;
+    } | {
+        notifications: {
+            id: string;
+            title: string;
+            body: string;
+        }[];
+        error?: undefined;
+        scheduled?: undefined;
+        notificationId?: undefined;
+        cancelled?: undefined;
+    } | {
+        cancelled: boolean;
+        error?: undefined;
+        scheduled?: undefined;
+        notificationId?: undefined;
+        notifications?: undefined;
+    }>;
+};

package/dist/lib/tools/registry.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Mobile tool registry — registers the mobile-specific tool set.
+ * Checks connectivity before exposing online-only tools.
+ */
+export interface MobileTool {
+    name: string;
+    description: string;
+    parameters?: Record<string, {
+        type: string;
+        description?: string;
+        required?: boolean;
+    }>;
+    handler: (params: Record<string, unknown>) => Promise<unknown>;
+    /** If true, this tool requires network connectivity. */
+    requiresNetwork?: boolean;
+}
+export interface MobileToolRegistryConfig {
+    tools: MobileTool[];
+    isOnline?: () => boolean;
+}
+export declare function createMobileToolRegistry(config: MobileToolRegistryConfig): {
+    listAvailable: () => MobileTool[];
+    get: (name: string) => MobileTool | undefined;
+    isExcluded: (name: string) => boolean;
+    EXCLUDED: string[];
+};

package/dist/lib/tools/reminders.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Reminders tool adapter — wraps expo-calendar reminders API (iOS).
+ */
+export interface RemindersAdapter {
+    requestRemindersPermissions(): Promise<{
+        status: string;
+    }>;
+    getRemindersAsync(calendarIds: string[]): Promise<Reminder[]>;
+    createReminderAsync(calendarId: string, details: Record<string, unknown>): Promise<string>;
+    getCalendarsAsync(entityType: string): Promise<Array<{
+        id: string;
+        title: string;
+    }>>;
+}
+export interface Reminder {
+    id: string;
+    title: string;
+    dueDate?: string;
+    completed: boolean;
+    notes?: string;
+}
+export declare function createRemindersTool(reminders: RemindersAdapter): {
+    name: "device.reminders";
+    description: string;
+    parameters: {
+        action: {
+            type: "string";
+            description: string;
+            required: boolean;
+        };
+        title: {
+            type: "string";
+            description: string;
+        };
+        dueDate: {
+            type: "string";
+            description: string;
+        };
+        notes: {
+            type: "string";
+            description: string;
+        };
+    };
+    handler: (params: Record<string, unknown>) => Promise<{
+        error: string;
+        reminders?: undefined;
+        created?: undefined;
+        reminderId?: undefined;
+    } | {
+        reminders: {
+            id: string;
+            title: string;
+            dueDate: string | null;
+            completed: boolean;
+        }[];
+        error?: undefined;
+        created?: undefined;
+        reminderId?: undefined;
+    } | {
+        created: boolean;
+        reminderId: string;
+        error?: undefined;
+        reminders?: undefined;
+    }>;
+};

package/dist/platforms/android-xr/XRAgentService.d.ts

@@ -0,0 +1,27 @@
+/**
+ * XR Agent Service — persistent background service running the agent loop
+ * on Android XR glasses. Coordinates voice, vision, gestures, notifications,
+ * and the display adapter.
+ */
+import { type VoiceInterfaceConfig, type VoiceInterface } from "./XRVoiceInterface.js";
+import { type ContextCaptureConfig, type ContextCapture } from "./XRContextCapture.js";
+import { type GestureHandlerConfig, type GestureHandler } from "./XRGestureHandler.js";
+import { type NotificationBridgeConfig, type NotificationBridge } from "./XRNotificationBridge.js";
+export interface XRAgentServiceConfig {
+    voice: VoiceInterfaceConfig;
+    context: ContextCaptureConfig;
+    gesture?: GestureHandlerConfig;
+    notification?: NotificationBridgeConfig;
+    /** Process a text query through the agent and return a response. */
+    processQuery: (text: string, imageData?: string) => Promise<string>;
+}
+export interface XRAgentService {
+    start(): void;
+    stop(): void;
+    isRunning(): boolean;
+    voice: VoiceInterface;
+    context: ContextCapture;
+    gesture: GestureHandler;
+    notification: NotificationBridge;
+}
+export declare function createXRAgentService(config: XRAgentServiceConfig): XRAgentService;

package/dist/platforms/android-xr/XRContextCapture.d.ts

@@ -0,0 +1,47 @@
+/**
+ * XR Context Capture — camera frame capture for vision queries.
+ * "What am I looking at?" captures the current frame and routes
+ * through the vision provider.
+ */
+export interface CameraFrame {
+    /** Base64-encoded JPEG image data. */
+    data: string;
+    /** Image width in pixels. */
+    width: number;
+    /** Image height in pixels. */
+    height: number;
+    /** Capture timestamp (ISO 8601). */
+    timestamp: string;
+    /** Camera source. */
+    source: "main" | "wide" | "depth";
+}
+export interface VisionProvider {
+    /** Describe what's in the image. */
+    describe(frame: CameraFrame, prompt?: string): Promise<string>;
+    /** Whether this provider works offline. */
+    isOffline: boolean;
+}
+export interface CameraAccess {
+    /** Capture a single frame from the glasses camera. */
+    captureFrame(source?: "main" | "wide"): Promise<CameraFrame>;
+    /** Check if camera permission is granted. */
+    hasPermission(): boolean;
+    /** Request camera permission. */
+    requestPermission(): Promise<boolean>;
+}
+export interface ContextCaptureConfig {
+    camera: CameraAccess;
+    visionProvider: VisionProvider;
+    /** Offline fallback vision provider (on-device model). */
+    offlineVisionProvider?: VisionProvider;
+    isOnline?: () => boolean;
+}
+export interface ContextCapture {
+    /** Capture current view and describe it. */
+    describeView(prompt?: string): Promise<string>;
+    /** Capture a frame without description (for later processing). */
+    captureFrame(): Promise<CameraFrame>;
+    /** Check if vision queries are available. */
+    isAvailable(): boolean;
+}
+export declare function createContextCapture(config: ContextCaptureConfig): ContextCapture;

package/dist/platforms/android-xr/XRGestureHandler.d.ts

@@ -0,0 +1,41 @@
+/**
+ * XR Gesture Handler — touchpad and head gesture input for Android XR glasses.
+ *
+ * Android XR glasses hardware:
+ * - Touchpad: right temple, swipe (up/down/left/right) + tap + long press
+ * - Camera button: short press = photo, long press = agent activation
+ * - Power button: press = sleep/wake
+ * - Head gestures: nod (yes), shake (no), tilt (dismiss)
+ */
+export type TouchpadGesture = "tap" | "double_tap" | "long_press" | "swipe_up" | "swipe_down" | "swipe_left" | "swipe_right";
+export type HeadGesture = "nod" | "shake" | "tilt_left" | "tilt_right";
+export type HardwareButton = "camera_short" | "camera_long";
+export type XRInputEvent = {
+    source: "touchpad";
+    gesture: TouchpadGesture;
+    timestamp: number;
+} | {
+    source: "head";
+    gesture: HeadGesture;
+    timestamp: number;
+} | {
+    source: "button";
+    gesture: HardwareButton;
+    timestamp: number;
+};
+export type XRAction = "activate_agent" | "send_message" | "cancel" | "scroll_up" | "scroll_down" | "dismiss" | "confirm" | "deny" | "pin_card" | "none";
+export interface GestureMapping {
+    touchpad: Record<TouchpadGesture, XRAction>;
+    head: Record<HeadGesture, XRAction>;
+    button: Record<HardwareButton, XRAction>;
+}
+export interface GestureHandlerConfig {
+    mapping?: Partial<GestureMapping>;
+    onAction?: (action: XRAction, event: XRInputEvent) => void;
+}
+export interface GestureHandler {
+    handleEvent(event: XRInputEvent): XRAction;
+    getMapping(): GestureMapping;
+    setMapping(updates: Partial<GestureMapping>): void;
+}
+export declare function createGestureHandler(config?: GestureHandlerConfig): GestureHandler;