FACTUAL ACTIVITY RECORD · An activity record based on work that took place
Building a Connector to safely synchronize local AI conversations
Continuously transferring display snapshots through read-only collection, a durable outbox, and authenticated batch ingestion
Purpose
If the 3D interface read local AI tasks and conversations directly, stopping the source machine would also make stored history unavailable, and notifications across processes could not serve as the source of truth. An independent process was needed to re-read local history and safely synchronize display snapshots to an external database.
The aim was a headless Connector that keeps privileged secrets off the device, preserves order during network failures, prioritizes active work while backfilling older history, and remains consistent across retries and large histories.
Implementation
local-history client and root-task reader start and initialize the app server over stdio, then re-read thread/list and thread/read for an exactly matching workspace. Notifications from another process are not treated as authoritative; fetched results are normalized to an allowlist of fields in history normalizer.
- Eight recently updated root and subagent threads plus their parent chains form the priority batch, with up to four reads in parallel.
- Remaining history is backfilled 32 threads at a time on a default 30-minute interval, keeping routine polling independent of the full-history duration.
- The first run performs a full scan, while restart with a checkpoint resumes from the priority batch.
durable outbox persists each fetched batch to SQLite before sending it in FIFO order. Monotonic sequences and idempotent batch identity prevent an old retry from overwriting newer state. Histories larger than 4 MiB are fragmented, and missing turns and messages are reconciled only when a complete ID manifest is available.
The device stores only a browser-safe publishable key and a user session. restricted ingestion endpoint and the heartbeat function verify the JWT before calling a privileged transactional RPC. Owner-scoped row controls cover devices, projects, definitions, threads, turns, messages, and batches.
- Reasoning, commands, tool arguments and results, and structured workspace and Git-remote fields are not synchronized.
- User and AI message bodies are synchronized verbatim, with an explicit warning that secrets or paths pasted into messages are not automatically redacted.
- command entry provides login, one-shot and continuous synchronization, status, diagnostics, retry of permanently blocked batches, and service management.
Boundary testing exposed problems in deleted-item reconciliation for huge threads, long agent keys, agent definitions exceeding 4 MiB, and metadata truncation splitting emoji. The implementation was corrected with ID-manifest reconciliation, byte-length limits, definition-size guarantees, and Unicode-scalar normalization, then retested near the limits.
The Connector sequenced retrieval, normalization, a durable outbox, and remote ingestion through one Collector. The browser application had no path to read local sources directly.
Rendering diagram…
What was confirmed
Verification results
The combined type-check, full-test, and build check passed on the final implementation.
Two hundred near-maximum agent metadata entries occupied about 2.39 MiB, leaving about 1.80 MiB below the 4 MiB limit.
C0 controls, unpaired surrogates, long identity names, huge-history fragmentation, retry ordering, and tombstone reconciliation boundaries were tested.
Implementation and documentation agreed on keeping secret keys and database passwords off the device, denying direct writes, and not automatically redacting raw message bodies.
At the cutoff, the initial Connector implementation had been applied to the target. New collection while the machine is asleep or stopped, full reconciliation for an extreme ID manifest, and automatic removal of secrets pasted into messages were not guaranteed.
Basis for completion
The initial scope was complete when read-only collection, priority scanning and backfill, a durable outbox, authenticated ingestion, owner boundaries, and large-input handling were present, the identified size, Unicode, and reconciliation problems were fixed, the final check passed, and the result was applied to the target.