EdgeCloudSync is a client for your application’s HTTP endpoints. It sends heartbeats, fetches admin blueprints, and keeps a bounded local JSONL queue of events. It does not supply a cloud server, apply downloaded configuration, or recreate the device’s Agents.
Begin after the device application works locally. Decide which events must leave the device and which service owns their receipts.
Implement the receiving contract
The client appends these paths tocloudUrl. It sends Authorization: Bearer <authToken> when configured. Authenticate the device and authorize its data at the receiver; a deviceId field is not proof of identity.
The admin package can provide the three configuration routes. It does not provide
/edge/heartbeat or /edge/events; implement those in your host. An empty 204 response is insufficient because this client parses response JSON.
A successful events response acknowledges the whole submitted batch; there is no partial receipt protocol. Deduplicate receipts using the authenticated device and event ID. If the receiver stores a batch but its response is lost, the client may send those same events again.
Quick start
Install@agentium/core@4.0.0 and @agentium/edge@4.0.0. This is a host integration factory: the caller supplies a working service URL, a device identity/token, and a writable persistent queue directory. Calling it starts HTTP requests and timers; it does not create a receiver.
reportHealth() with a snapshot when your host wants to transmit measurements.
After the first successful heartbeat, sync.isConnected becomes true. Call reportRun() and inspect sync.queueSize or await sync.flush() for { sent, failed, remaining }. A successful request only establishes that endpoint’s response, not that all dependencies are healthy.
Features
Heartbeat
start() sends an initial heartbeat and schedules later heartbeats and flushes. An initial failure leaves isConnected false; the disconnected event describes a transition from an earlier connected state, so it need not fire on initial startup failure. Use state and receiver logs when diagnosing initial connectivity.
Config pull
pullConfig() fetches three arrays and returns them. It does not poll configuration automatically or apply it. On failure it emits config-pull-error and returns empty arrays; treat those arrays as an unavailable result, not an instruction to delete local configuration.
The returned entries are unknown. Validate the fields your application accepts before presenting or applying them. This example only reads a proposal; it creates no Agents:
zod@4 for this validation example. Add application policy for permitted providers, tool names, model IDs, and device capabilities. Stage changes, finish or cancel work according to host policy, create the replacement instances, and then change routing. Neither cloud sync nor admin hydration implements that rollout for you. Workflow metadata contains no executable step graph.
Event push
pushEvent() queues the payload locally and attempts a flush when the client believes the service is connected. It returns before a network acknowledgment; await flush() when you need the batch result. Concurrent flush calls share the pending flush, and newly queued events remain for a later batch.
Send the metadata your receiving application needs. Including prompt text, tool outputs, or device data is a host choice, not a requirement of this protocol.
Offline-first queue
Events are kept in memory and written to<queueDir>/<deviceId>.jsonl. After a successful acknowledged batch, those submitted IDs are removed. The default directory is /tmp/agentium-edge-queue, which may not survive device reboot or temporary-file cleanup. Select a persistent host directory for retention across those failures.
The queue drops the oldest events when maxQueueSize is exceeded. File persistence is best effort; write failures are swallowed, and unreadable/malformed queue contents can be lost on load. This is a bounded telemetry queue, not a durable action ledger or guaranteed audit log. Use an appropriate durable store for operations whose recovery depends on authoritative records.
Config
The timer interval determines scheduled retries. Do not assume adaptive retry timing from the client’s internal backoff bookkeeping. Requests have no exposed per-request timeout/abort option; account for stalled network requests in your host’s shutdown and process-supervision policy.
Events
queue-loaded is emitted during construction, before later listeners can attach. Inspect queueSize immediately after constructing the client to observe restored work.
Shutdown and verification
Stop event producers, callstop() to clear timers and persist the current queue, then await a final flush() if your shutdown policy allows network delivery. Inspect remaining and preserve the queue directory. stop() does not cancel already active HTTP requests.
Before using a real device, exercise your receiver with these cases:
- Reject missing or wrong device credentials.
- Accept a heartbeat with valid JSON, then acknowledge an event batch.
- Resend the same event IDs and verify receiver deduplication.
- Make the receiver unavailable, queue work, restart the client, then reconnect.
- Reject an invalid configuration proposal without changing the active Agent.