Skip to content

YC (S26) | Open Computer History | Continuously record your company computer work, map your workflows, help you find work worth automating, and power your agents' context

feat(enterprise): report recording lifecycle with durable offline backfill (#7732)

Ezra Ellette9334c1f6368b
diff --git a/apps/screenpipe-app-tauri/src-tauri/src/capture_session.rs b/apps/screenpipe-app-tauri/src-tauri/src/capture_session.rs
index da697b3f3..c74dc4a82 100644
--- a/apps/screenpipe-app-tauri/src-tauri/src/capture_session.rs
+++ b/apps/screenpipe-app-tauri/src-tauri/src/capture_session.rs
@@ -328,6 +328,10 @@ impl CaptureSession {
screenpipe_engine::meeting_watcher::set_capture_stopped(false);
info!("Capture session started successfully");
+ #[cfg(feature = "enterprise-build")]
+ crate::enterprise::recording_events::record(
+ crate::enterprise::recording_events::State::Started,
+ );
Ok(Self {
shutdown_tx,
@@ -431,8 +435,16 @@ impl CaptureSession {
info!("Capture session stopped");
if failures.is_empty() {
+ #[cfg(feature = "enterprise-build")]
+ crate::enterprise::recording_events::record(
+ crate::enterprise::recording_events::State::Paused,
+ );
Ok(())
} else {
+ #[cfg(feature = "enterprise-build")]
+ crate::enterprise::recording_events::record(
+ crate::enterprise::recording_events::State::Unknown,
+ );
Err(failures.join("; "))
}
}
diff --git a/apps/screenpipe-app-tauri/src-tauri/src/diagnostic_logs.rs b/apps/screenpipe-app-tauri/src-tauri/src/diagnostic_logs.rs
index b1d01e105..24c4f3f64 100644
--- a/apps/screenpipe-app-tauri/src-tauri/src/diagnostic_logs.rs
+++ b/apps/screenpipe-app-tauri/src-tauri/src/diagnostic_logs.rs
@@ -236,6 +236,36 @@ async fn build_bundle(files: &[LogFile]) -> String {
mod tests {
use super::*;
+ #[cfg(feature = "enterprise-build")]
+ #[tokio::test]
+ async fn recording_event_missing_ack_survives_support_collection() {
+ let root = tempfile::tempdir().unwrap();
+ crate::enterprise::recording_events::bind(
+ root.path(),
+ "support-fixture",
+ "device",
+ "endpoint",
+ );
+ let (path, event) =
+ crate::enterprise::recording_events::pending("device", "endpoint").unwrap();
+ crate::enterprise::recording_events::acknowledge(
+ &path,
+ &event,
+ &serde_json::json!({"ok": true, "recording_event_error": "persistence_failed", "recording_event_storage_code": "42P01"}),
+ );
+ let report = collect_redacted_from_dirs(&[root.path().to_owned()])
+ .await
+ .unwrap();
+ assert!(report.contains("enterprise_recording_events_failed"));
+ assert!(report.contains("persistence_failed"));
+ assert!(report.contains("42P01"));
+ assert!(report.contains("delivery_pending"));
+ assert!(
+ path.exists(),
+ "support collection must preserve pending events"
+ );
+ }
+
#[tokio::test(flavor = "current_thread")]
async fn required_pii_failure_survives_rotation_and_support_redaction() {
use std::sync::Arc;
diff --git a/apps/screenpipe-app-tauri/src-tauri/src/enterprise/mod.rs b/apps/screenpipe-app-tauri/src-tauri/src/enterprise/mod.rs
index 19fa3222c..9ff763523 100644
--- a/apps/screenpipe-app-tauri/src-tauri/src/enterprise/mod.rs
+++ b/apps/screenpipe-app-tauri/src-tauri/src/enterprise/mod.rs
@@ -14,3 +14,6 @@ pub mod device_config;
#[cfg(feature = "enterprise-build")]
pub mod managed_settings;
+
+#[cfg(feature = "enterprise-build")]
+pub(crate) mod recording_events;
diff --git a/apps/screenpipe-app-tauri/src-tauri/src/enterprise/recording_events.rs b/apps/screenpipe-app-tauri/src-tauri/src/enterprise/recording_events.rs
new file mode 100644
index 000000000..47b64c731
--- /dev/null
+++ b/apps/screenpipe-app-tauri/src-tauri/src/enterprise/recording_events.rs
@@ -0,0 +1,382 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+
+//! Durable, content-free capture lifecycle outbox. Session boundaries are not
+//! proof of persisted frames/audio. Never pair events across process sessions.
+
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::{LazyLock, Mutex};
+
+static OUTBOX: Mutex<Option<Outbox>> = Mutex::new(None);
+static SESSION: LazyLock<String> = LazyLock::new(|| uuid::Uuid::new_v4().to_string());
+static CHANGED: tokio::sync::Notify = tokio::sync::Notify::const_new();
+static SEQUENCE: AtomicU64 = AtomicU64::new(0);
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub(crate) struct Event {
+ pub event_id: String,
+ pub license_id: String,
+ pub device_id: String,
+ pub session_id: String,
+ pub sequence: u64,
+ pub occurred_at: String,
+ pub state: State,
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum State {
+ Started,
+ Paused,
+ Unknown,
+}
+
+struct Outbox {
+ root: PathBuf,
+ directory: PathBuf,
+ license_id: String,
+ device_id: String,
+ endpoint: String,
+}
+
+impl Outbox {
+ fn open(root: &Path, license_id: &str, device_id: &str, endpoint: &str) -> Self {
+ let mut hash = Sha256::new();
+ for value in [license_id, device_id, endpoint] {
+ hash.update(value.as_bytes());
+ hash.update([0]);
+ }
+ Self {
+ root: root.to_owned(),
+ directory: root
+ .join("enterprise-recording-events")
+ .join(format!("{:x}", hash.finalize())),
+ license_id: license_id.into(),
+ device_id: device_id.into(),
+ endpoint: endpoint.into(),
+ }
+ }
+
+ fn record(&mut self, state: State) -> Result<(), String> {
+ let event = Event {
+ event_id: uuid::Uuid::new_v4().to_string(),
+ license_id: self.license_id.clone(),
+ device_id: self.device_id.clone(),
+ session_id: SESSION.clone(),
+ sequence: SEQUENCE.fetch_add(1, Ordering::SeqCst) + 1,
+ occurred_at: chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Millis, true),
+ state,
+ };
+ std::fs::create_dir_all(&self.directory).map_err(|e| e.to_string())?;
+ sync_directory(self.directory.parent().unwrap())?;
+ sync_directory(&self.root)?;
+ let mut file =
+ tempfile::NamedTempFile::new_in(&self.directory).map_err(|e| e.to_string())?;
+ serde_json::to_writer(&mut file, &event).map_err(|e| e.to_string())?;
+ file.flush().map_err(|e| e.to_string())?;
+ file.as_file().sync_all().map_err(|e| e.to_string())?;
+ file.persist(self.directory.join(format!("{}.json", event.event_id)))
+ .map_err(|e| e.to_string())?;
+ sync_directory(&self.directory)?;
+ CHANGED.notify_one();
+ Ok(())
+ }
+
+ // One file per request keeps delivery streaming regardless of offline backlog.
+ fn pending(&self) -> Result<Option<(PathBuf, Event)>, String> {
+ let entries = match std::fs::read_dir(&self.directory) {
+ Ok(entries) => entries,
+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+ Err(e) => return Err(e.to_string()),
+ };
+ for entry in entries {
+ let entry = entry.map_err(|e| e.to_string())?;
+ if entry.path().extension().and_then(|s| s.to_str()) != Some("json") {
+ continue;
+ }
+ if !entry.file_type().map_err(|e| e.to_string())?.is_file() {
+ return Err("recording event is not an owned regular file".into());
+ }
+ let event: Event =
+ serde_json::from_slice(&std::fs::read(entry.path()).map_err(|e| e.to_string())?)
+ .map_err(|e| e.to_string())?;
+ if event.license_id != self.license_id || event.device_id != self.device_id {
+ return Err("recording event scope mismatch; pending event retained".into());
+ }
+ return Ok(Some((entry.path(), event)));
+ }
+ Ok(None)
+ }
+}
+
+fn sync_directory(path: &Path) -> Result<(), String> {
+ #[cfg(unix)]
+ std::fs::File::open(path)
+ .and_then(|file| file.sync_all())
+ .map_err(|e| e.to_string())?;
+ Ok(())
+}
+
+fn diagnostic(root: &Path, cause: &str) {
+ crate::recording::recovery_log::append(
+ root,
+ "enterprise_recording_events_failed",
+ &format!(
+ "cause={cause}; outcome=timeline_incomplete_or_delivery_pending; capture_continues"
+ ),
+ );
+}
+
+/// Bind only from an authenticated policy response, before starting capture.
+/// Changing keys within a workspace keeps its backlog; changing workspace or
+/// endpoint leaves the old backlog isolated for that original destination.
+pub(crate) fn bind(root: &Path, license_id: &str, device_id: &str, endpoint: &str) {
+ let mut guard = OUTBOX.lock().unwrap_or_else(|e| e.into_inner());
+ if guard.as_ref().is_some_and(|outbox| {
+ outbox.license_id == license_id
+ && outbox.device_id == device_id
+ && outbox.endpoint == endpoint
+ }) {
+ return;
+ }
+ let mut outbox = Outbox::open(root, license_id, device_id, endpoint);
+ if let Err(error) = outbox.record(State::Unknown) {
+ diagnostic(root, &error);
+ }
+ *guard = Some(outbox);
+}
+
+pub(crate) fn record(state: State) {
+ let mut guard = OUTBOX.lock().unwrap_or_else(|e| e.into_inner());
+ if let Some(outbox) = guard.as_mut() {
+ if let Err(error) = outbox.record(state) {
+ diagnostic(&outbox.root, &error);
+ }
+ }
+}
+
+pub(crate) async fn changed() {
+ CHANGED.notified().await;
+}
+
+pub(crate) fn delivery_failed(event: &Event, cause: &str) {
+ if let Some(outbox) = OUTBOX.lock().unwrap_or_else(|e| e.into_inner()).as_ref() {
+ diagnostic(
+ &outbox.root,
+ &format!(
+ "event_id={}; {cause}; retry=next_enterprise_policy_poll",
+ event.event_id
+ ),
+ );
+ }
+}
+
+pub(crate) async fn send_heartbeat(
+ request: reqwest::RequestBuilder,
+ pending: Option<(PathBuf, Event)>,
+) -> Result<(reqwest::StatusCode, serde_json::Value), reqwest::Error> {
+ let response = request.send().await.map_err(|error| {
+ let error = error.without_url();
+ if let Some((_, event)) = &pending {
+ delivery_failed(event, &format!("heartbeat request: {error:?}"));
+ }
+ error
+ })?;
+ let status = response.status();
+ let body = match response.json::<serde_json::Value>().await {
+ Ok(body) => body,
+ Err(error) => {
+ if let Some((_, event)) = &pending {
+ delivery_failed(
+ event,
+ &format!("heartbeat response HTTP {status}: {error:?}"),
+ );
+ }
+ serde_json::Value::Null
+ }
+ };
+ if let Some((path, event)) = pending {
+ if status.is_success() {
+ acknowledge(&path, &event, &body);
+ } else {
+ delivery_failed(&event, &format!("heartbeat HTTP {status}"));
+ }
+ }
+ Ok((status, body))
+}
+
+pub(crate) fn pending(device_id: &str, endpoint: &str) -> Option<(PathBuf, Event)> {
+ let guard = OUTBOX.lock().unwrap_or_else(|e| e.into_inner());
+ let outbox = guard.as_ref()?;
+ if outbox.device_id != device_id || outbox.endpoint != endpoint {
+ return None;
+ }
+ match outbox.pending() {
+ Ok(event) => event,
+ Err(error) => {
+ diagnostic(&outbox.root, &error);
+ None
+ }
+ }
+}
+
+/// HTTP success alone is insufficient: older servers ignore unknown fields.
+pub(crate) fn acknowledge(path: &Path, event: &Event, receipt: &serde_json::Value) {
+ let result = if receipt["recording_event_ack"].as_str() == Some(event.event_id.as_str()) {
+ std::fs::remove_file(path)
+ .or_else(|error| {
+ // Startup authorization and the watcher can acknowledge the
+ // same event concurrently. Both receipts confirm persistence.
+ if error.kind() == std::io::ErrorKind::NotFound {
+ Ok(())
+ } else {
+ Err(error)
+ }
+ })
+ .map_err(|e| e.to_string())
+ .and_then(|_| sync_directory(path.parent().unwrap()))
+ } else {
+ Err(format!(
+ "recording event {} not acknowledged; server_code={}; storage_code={}",
+ event.event_id,
+ receipt["recording_event_error"]
+ .as_str()
+ .unwrap_or("missing_ack"),
+ receipt["recording_event_storage_code"]
+ .as_str()
+ .unwrap_or("unknown")
+ ))
+ };
+ if let Err(error) = result {
+ if let Some(outbox) = OUTBOX.lock().unwrap_or_else(|e| e.into_inner()).as_ref() {
+ diagnostic(&outbox.root, &error);
+ }
+ } else {
+ // Drain without waiting for the normal policy poll, one event at a time.
+ CHANGED.notify_one();
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn transitions_survive_restart_and_keep_identity_and_original_times() {
+ let root = tempfile::tempdir().unwrap();
+ let mut outbox = Outbox::open(root.path(), "workspace", "device", "endpoint");
+ outbox.record(State::Started).unwrap();
+ outbox.record(State::Paused).unwrap();
+ let reopened = Outbox::open(root.path(), "workspace", "device", "endpoint");
+ let (path, original) = reopened.pending().unwrap().unwrap();
+ assert_eq!(reopened.pending().unwrap().unwrap().1, original);
+ acknowledge(&path, &original, &serde_json::json!({"ok": true}));
+ assert!(path.exists());
+ acknowledge(
+ &path,
+ &original,
+ &serde_json::json!({"recording_event_ack": "wrong"}),
+ );
+ assert!(path.exists());
+ acknowledge(
+ &path,
+ &original,
+ &serde_json::json!({"recording_event_ack": original.event_id}),
+ );
+ assert!(!path.exists());
+ let (_, remaining) = reopened.pending().unwrap().unwrap();
+ assert_ne!(original.event_id, remaining.event_id);
+ assert_ne!(original.sequence, remaining.sequence);
+ assert_eq!(original.session_id, remaining.session_id);
+ }
+
+ #[test]
+ fn workspace_device_and_destination_backlogs_are_isolated() {
+ let root = tempfile::tempdir().unwrap();
+ let mut outbox = Outbox::open(root.path(), "a", "device", "endpoint");
+ outbox.record(State::Started).unwrap();
+ for (workspace, device, endpoint) in [
+ ("b", "device", "endpoint"),
+ ("a", "other", "endpoint"),
+ ("a", "device", "other"),
+ ] {
+ assert!(Outbox::open(root.path(), workspace, device, endpoint)
+ .pending()
+ .unwrap()
+ .is_none());
+ }
+ assert!(outbox.pending().unwrap().is_some());
+ }
+
+ #[test]
+ fn corrupted_events_are_retained_as_actionable_failures() {
+ let root = tempfile::tempdir().unwrap();
+ let mut outbox = Outbox::open(root.path(), "a", "device", "endpoint");
+ outbox.record(State::Started).unwrap();
+ let (path, _) = outbox.pending().unwrap().unwrap();
+ std::fs::write(&path, b"broken").unwrap();
+ assert!(outbox.pending().is_err());
+ assert!(path.exists());
+ }
+
+ #[tokio::test]
+ async fn failed_http_and_missing_receipts_survive_restart_then_backfill() {
+ use wiremock::{matchers::method, Mock, MockServer, ResponseTemplate};
+ let server = MockServer::start().await;
+ let http = reqwest::Client::new();
+ let root = tempfile::tempdir().unwrap();
+ let mut outbox = Outbox::open(root.path(), "workspace", "device", &server.uri());
+ outbox.record(State::Started).unwrap();
+ outbox.record(State::Paused).unwrap();
+ let pending = outbox.pending().unwrap();
+ let failed_path = pending.as_ref().unwrap().0.clone();
+ assert!(send_heartbeat(http.post("http://127.0.0.1:0"), pending)
+ .await
+ .is_err());
+ assert!(failed_path.exists());
+ for response in [
+ ResponseTemplate::new(503),
+ ResponseTemplate::new(200).set_body_json(serde_json::json!({"ok": true})),
+ ResponseTemplate::new(200).set_body_string("broken"),
+ ] {
+ server.reset().await;
+ Mock::given(method("POST"))
+ .respond_with(response)
+ .mount(&server)
+ .await;
+ let pending = outbox.pending().unwrap();
+ let path = pending.as_ref().unwrap().0.clone();
+ send_heartbeat(
+ http.post(server.uri()).json(&pending.as_ref().unwrap().1),
+ pending,
+ )
+ .await
+ .unwrap();
+ assert!(path.exists());
+ }
+ // A process restart reopens files rather than manufacturing new IDs/times.
+ let reopened = Outbox::open(root.path(), "workspace", "device", &server.uri());
+ let mut delivered = 0;
+ while let Some(pending) = reopened.pending().unwrap() {
+ server.reset().await;
+ let event = pending.1.clone();
+ Mock::given(method("POST"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(
+ serde_json::json!({"ok": true, "recording_event_ack": event.event_id}),
+ ))
+ .mount(&server)
+ .await;
+ send_heartbeat(http.post(server.uri()).json(&event), Some(pending))
+ .await
+ .unwrap();
+ let requests = server.received_requests().await.unwrap();
+ assert_eq!(requests[0].body_json::<Event>().unwrap(), event);
+ delivered += 1;
+ }
+ assert_eq!(delivered, 2);
+ }
+}
diff --git a/apps/screenpipe-app-tauri/src-tauri/src/enterprise_sync.rs b/apps/screenpipe-app-tauri/src-tauri/src/enterprise_sync.rs
index c6e144c93..816d48155 100644
--- a/apps/screenpipe-app-tauri/src-tauri/src/enterprise_sync.rs
+++ b/apps/screenpipe-app-tauri/src-tauri/src/enterprise_sync.rs
@@ -1319,6 +1319,8 @@ mod imp {
#[derive(Deserialize)]
struct NativePolicyResponse {
+ #[serde(rename = "licenseId", default)]
+ license_id: Option<String>,
#[serde(rename = "hiddenSections", default)]
hidden_sections: Vec<String>,
#[serde(rename = "lockedSettings", default)]
@@ -1508,11 +1510,22 @@ mod imp {
"policy",
));
}
- let policy = response
+ let response = response
.json::<NativePolicyResponse>()
.await
- .map(NativePolicyResponse::into_native_policy)
.map_err(|error| NativePolicyFetchError::Unavailable(error.to_string()))?;
+ if let Some(license_id) = response.license_id.as_deref() {
+ // Authenticate the workspace independently of rotating keys/tokens.
+ // Resolve the configured heartbeat URL too, including custom routes.
+ let (_, endpoint) = authorization_endpoint_urls();
+ crate::enterprise::recording_events::bind(
+ &crate::config::app_data_dir(),
+ license_id,
+ device_id,
+ &endpoint,
+ );
+ }
+ let policy = response.into_native_policy();
// GET authenticated this workspace's policy. Apply AI setup before
// recording-paused branches or fallible enrollment/settings work can
// discard it. This never grants recording or bypasses seat checks.
@@ -1593,37 +1606,32 @@ mod imp {
credential: &EnterprisePolicyCredential,
measurement: Option<&RecordingMeasurement>,
) -> Result<(), NativePolicyFetchError> {
+ let pending = crate::enterprise::recording_events::pending(device_id, heartbeat_url);
let request = http.post(heartbeat_url).json(&serde_json::json!({
"device_id": device_id,
"hostname": hostname::get().ok().and_then(|value| value.into_string().ok()),
"platform": std::env::consts::OS,
"app_version": env!("CARGO_PKG_VERSION"),
"recording_lifecycle": crate::search_only::recording_lifecycle(),
+ "recording_event": pending.as_ref().map(|(_, event)| event),
"recording_status": {
"frame_status": measurement.and_then(|value| value.frame_status.as_deref()).unwrap_or("unknown"),
"audio_status": measurement.and_then(|value| value.audio_status.as_deref()).unwrap_or("unknown"),
},
}));
let request = apply_enterprise_credential(request, credential);
- let response = request
- .send()
+ let (status, body) = crate::enterprise::recording_events::send_heartbeat(request, pending)
.await
.map_err(|error| NativePolicyFetchError::Unavailable(error.to_string()))?;
- if response.status().is_success() {
+ if status.is_success() {
return Ok(());
}
-
- let status = response.status();
- let code = response
- .json::<EnterpriseErrorResponse>()
- .await
- .ok()
- .and_then(|body| body.code);
+ let code = body.get("code").and_then(|value| value.as_str());
// Generic 403 still includes seat exhaustion. Policy validity alone
// must never bypass the enrollment limit that heartbeat enforces.
Err(classify_failed_enterprise_response(
status,
- code.as_deref(),
+ code,
"heartbeat",
))
}
@@ -2086,6 +2094,26 @@ mod imp {
let _ =
crate::enterprise_recording_access::revoke_enterprise_recording(&app)
.await;
+ // Stop capture before any reporting I/O: a failed
+ // heartbeat must never delay the admin's pause.
+ if crate::enterprise::recording_events::pending(&device_id, &heartbeat_url)
+ .is_some()
+ {
+ for credential in current_policy_credentials() {
+ if send_enrollment_heartbeat(
+ &http,
+ &heartbeat_url,
+ &device_id,
+ &credential,
+ None,
+ )
+ .await
+ .is_ok()
+ {
+ break;
+ }
+ }
+ }
}
NativeAuthorizationResult::RequiresAccount => {
warn!(
@@ -2124,6 +2152,7 @@ mod imp {
tokio::select! {
_ = tokio::time::sleep(next_poll) => {},
_ = crate::search_only::lifecycle_changed() => {},
+ _ = crate::enterprise::recording_events::changed() => {},
}
}
});
@@ -2213,7 +2242,9 @@ mod imp {
// Point the stalled-upload watchdog at the real app-log dirs. App logs
// live in the screenpipe data dir (RollingFileAppender), NOT Tauri's
// app_data_dir — so the from_env default would miss them.
- let mut log_dirs = Vec::new();
+ // Lifecycle outbox diagnostics live with settings, which can differ
+ // from the engine's current recording directory after a data move.
+ let mut log_dirs = vec![crate::config::app_data_dir().to_path_buf()];
if let Ok(d) = crate::log_files::get_screenpipe_data_dir(app) {
log_dirs.push(d);
}
@@ -3018,6 +3049,7 @@ mod imp {
#[test]
fn hidden_ui_policy_matches_frontend_section_normalization() {
let response = NativePolicyResponse {
+ license_id: None,
hidden_sections: vec!["app_ui".to_string(), "app_ui".to_string()],
locked_settings: HashMap::from([
("recording".to_string(), serde_json::Value::Bool(true)),
diff --git a/apps/screenpipe-app-tauri/src-tauri/tests/recording_events_test.rs b/apps/screenpipe-app-tauri/src-tauri/tests/recording_events_test.rs
new file mode 100644
index 000000000..fd9313775
--- /dev/null
+++ b/apps/screenpipe-app-tauri/src-tauri/tests/recording_events_test.rs
@@ -0,0 +1,14 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+
+#![cfg(feature = "enterprise-build")]
+
+#[path = "../src/recording/recovery_log.rs"]
+pub(crate) mod recovery_log;
+
+mod recording {
+ pub(crate) use crate::recovery_log;
+}
+
+#[path = "../src/enterprise/recording_events.rs"]
+mod recording_events;