Crate synheart_sensor_agent 

Synheart Sensor Agent

Privacy-first PC background sensor for behavioral research.

This library captures keyboard and mouse interaction timing for behavioral research with strong privacy guarantees. Raw events are never stored — only derived statistical features are produced as HSI 1.0 JSON snapshots.

Privacy Guarantees

• No key content — only timing and category (typing vs. navigation)
• No coordinates — only mouse movement magnitude/speed
• No raw storage — events are discarded after feature extraction (every 10 s)
• Transparency — all collection is logged and auditable via TransparencyLog

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Synheart Sensor Agent                    │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐        │
│  │  Collector  │──▶│  Windowing  │──▶│  Features   │        │
│  │ (platform)  │   │  (10s bins) │   │ (compute)   │        │
│  └─────────────┘   └─────────────┘   └─────────────┘        │
│         │                                    │              │
│         ▼                                    ▼              │
│  ┌─────────────┐                     ┌─────────────┐        │
│  │Transparency │                     │    HSI      │        │
│  │    Log      │                     │  Snapshot   │        │
│  └─────────────┘                     └─────────────┘        │
└─────────────────────────────────────────────────────────────┘

Quick Start

use synheart_sensor_agent::{collector, core, transparency};

// Create a collector (requires Input Monitoring permission on macOS)
let config = collector::CollectorConfig::default();
let mut collector = collector::Collector::new(config);

// Start collection
collector.start().expect("Failed to start collector");

// Events can be received from collector.receiver()

Modules

Module	Purpose
collector	Platform-specific event capture (SensorEvent, Collector)
config	Agent configuration and persistence (Config, SourceConfig)
core	Windowing, feature extraction, and HSI encoding (WindowManager, compute_features, HsiBuilder)
transparency	Auditable collection logging (TransparencyLog, TransparencyStats)
flux	Synheart Flux integration for baseline tracking (requires flux feature)
gateway	Gateway client for real-time HSI sync (requires gateway feature)
server	HTTP server for Chrome extension ingest (requires server feature)

Feature Flags

Feature	Description
flux	Enables SensorFluxProcessor for rolling baseline tracking via synheart-flux
gateway	Enables GatewayClient / BlockingGatewayClient for syncing HSI to the local gateway
server	Enables the HTTP ingest server for Chrome extension data (implies flux + gateway)

Platform Support

The collector module adapts to the build target:

• macOS — CoreGraphics event tap + NSWorkspace for foreground app detection
• Windows — Windows Hooks API for keyboard/mouse + foreground window detection
• Other — No-op collector (compiles but does not capture events)

Re-exports

pub use collector::Collector;

pub use collector::CollectorConfig;

pub use collector::CollectorError;

pub use collector::SensorEvent;

pub use config::Config;

pub use config::SourceConfig;

pub use core::compute_features;

pub use core::HsiBuilder;

pub use core::HsiSnapshot;

pub use core::WindowFeatures;

pub use core::WindowManager;

pub use transparency::SharedTransparencyLog;

pub use transparency::TransparencyLog;

pub use transparency::TransparencyStats;

pub use flux::EnrichedSnapshot;flux

pub use flux::SensorFluxProcessor;flux

pub use gateway::BlockingGatewayClient;gateway

pub use gateway::GatewayClient;gateway

pub use gateway::GatewayConfig;gateway

pub use gateway::GatewayError;gateway

pub use gateway::GatewayResponse;gateway

pub use server::run as run_server;server

pub use server::ServerConfig;server

Modules

collector

Platform-specific event collection (keyboard, mouse, shortcuts).

config

Agent configuration and persistence. Configuration for the Synheart Sensor Agent.

core

Core functionality — windowing, feature extraction, and HSI snapshot building. Core functionality for the Synheart Sensor Agent.

fluxflux

Synheart Flux integration for baseline tracking and HSI enrichment.

gatewaygateway

Gateway client for syncing HSI snapshots to the local synheart-core-gateway.

serverserver

HTTP server for receiving behavioral data from the Chrome extension.

transparency

Transparency logging for auditable data collection. Transparency module for the Synheart Sensor Agent.

Constants

PRIVACY_DECLARATION

Privacy declaration that can be displayed to users.

VERSION

Library version string sourced from Cargo.toml.