ambleloftSubscribe to business events
Connect your service to the extension backend, then publish, update or withdraw messages in Ambleloft.
Outcome: Receive demo service events and verify updates, disconnection and cleanup.
Before you begin: Prepare the files and tools specified on this page. The previous page in the learning path is not automatically a dependency.
On this page
01Build and install the sample
Use Node.js ≥22.13 and a current extension-capable host. These commands run from a fresh clone; install the resulting archive in Settings → Extensions and grant configuration/storage access. First obtain the matching sample source snapshot and complete local package setup in the first-extension guide. Run from the parent of ambleloft-extension-samples with AMBLELOFT_PACKS set.
cd ambleloft-extension-samples/service-events
npm install --save-dev "$AMBLELOFT_PACKS/ambleloft-extension-sdk-0.1.0-alpha.9.tgz" "$AMBLELOFT_PACKS/ambleloft-extension-core-0.1.0-alpha.9.tgz" "$AMBLELOFT_PACKS/ambleloft-extension-cli-0.1.0-alpha.9.tgz"
npm run build
npm run validate
npm test
npm run pack02Start the service and connect
Run the service in a separate terminal. Configure serviceUrl as http://127.0.0.1:47831/events in the extension, then click Connect and confirm. The sample intentionally permits only this loopback-style HTTP /events endpoint; it is not a general production SSE client.
npm run service03Send your first event
Run this in another terminal. Expect a local message titled Report ready. The response includes subscribers; zero means no client is connected. Sending the same event and version again should not create a new message.
curl http://127.0.0.1:47831/event \
-H 'content-type: application/json' \
-d '{"eventId":"report-42","taskId":"report","kind":"progress","version":1,"title":"Report ready","body":"Ready for review"}' 04Update and withdraw
Keep eventId=report-42, increment version to 2 and change body to update the existing message. Then send kind=withdraw with version=3 (keep required title/body/taskId fields) to withdraw it. Older versions are ignored. eventId identifies the message; taskId identifies your business task; version orders its events.
05Understand the implementation
src/push.ts owns one connection, serializes events, validates payloads and reconnects with capped backoff. src/extension.ts tracks versions in extension storage and calls getByEventKey → publish/update/withdraw. It adds the connection to context.subscriptions: closing the page leaves it active; Disconnect or extension deactivation disposes it.
Inspect the complete implementation06Exercise disconnects and limits
POST /disconnect to exercise reconnect, then send a newer event. The demo service has no durable event replay. Production integration needs a persisted cursor, replay/acknowledgment and reconciliation for pending events. The sample records pending before publication, so do not claim exactly-once delivery after a crash. These are your service events, not Agent conversation or turn lifecycle events.
curl -X POST http://127.0.0.1:47831/disconnect07Clean up and add actions
Disconnect the extension and stop the standalone service with Ctrl+C. Next, use message actions when users should approve or execute a business task from a message.
Add business actionsCheck the result and troubleshoot
Receive demo service events and verify updates, disconnection and cleanup.
Check actual results using this page’s verification steps. For business integrations, inspect UI submission, tool receipts and server records separately.
Open the error reference →