Run events

The transition ledger

A compile publishes its transitions to an append-only ledger. The event stream replays that ledger from Last-Event-ID and then follows it, so a client that reconnects sees everything it missed rather than the current state alone.

curl -sS -X GET https://tavonel.com/api/compile-jobs/{jobId}/events \
  -H "Authorization: Bearer $TAVONEL_API_KEY"

import os
import requests

response = requests.request(
    "GET",
    "https://tavonel.com/api/compile-jobs/{jobId}/events",
    headers={"Authorization": "Bearer " + os.environ["TAVONEL_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://tavonel.com/api/compile-jobs/{jobId}/events", {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.TAVONEL_API_KEY}` },
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());

curl -sS -X GET https://tavonel.com/api/compile-jobs/{jobId} \
  -H "Authorization: Bearer $TAVONEL_API_KEY"

import os
import requests

response = requests.request(
    "GET",
    "https://tavonel.com/api/compile-jobs/{jobId}",
    headers={"Authorization": "Bearer " + os.environ["TAVONEL_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://tavonel.com/api/compile-jobs/{jobId}", {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.TAVONEL_API_KEY}` },
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());

Resuming after a disconnect

curl -N https://tavonel.com/api/compile-jobs/<jobId>/events \
  -H "Authorization: Bearer $TAVONEL_API_KEY" \
  -H "Last-Event-ID: 42"

Reconnecting is the normal case

Note The server closes the stream on its own clock. Reconnecting is the normal case, not an error path — every frame carries the sequence to resume from.

The other stream: observed runs

A compile has its own transitions, above. A connector sync or an intake is an observed run, with its own append-only event ledger and its own stream. Both resume the same way, from Last-Event-ID; this one also accepts an after query parameter for clients that cannot set the header, and sends a bounded heartbeat so an intermediary does not close an idle connection.

curl -sS -X GET https://tavonel.com/api/v1/runs/{runId}/events \
  -H "Authorization: Bearer $TAVONEL_API_KEY"

import os
import requests

response = requests.request(
    "GET",
    "https://tavonel.com/api/v1/runs/{runId}/events",
    headers={"Authorization": "Bearer " + os.environ["TAVONEL_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://tavonel.com/api/v1/runs/{runId}/events", {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.TAVONEL_API_KEY}` },
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());

Change notifications

A stream needs a client holding it open. A change notification does not: when a finished compile's candidate differs from the World your AI currently reads, TAVONEL sends one signed POST to the endpoint registered for that workspace. Processing is automatic; activation is not. The candidate waits for a person to approve it in the workspace, and a notification activates nothing.

Note Before you start. Notifications are set up per workspace with us, like intake: we register your endpoint and give you that workspace's signing key, and until then nothing is sent. The endpoint must be https on the default port and must answer without a redirect. There are no email notifications.

Verifying a notification

Every request carries three headers: tavonel-delivery-id, tavonel-timestamp (Unix seconds) and tavonel-signature, which is v1= followed by a hex HMAC-SHA256. The signed string is the delivery id, the timestamp and the raw body, joined by dots. Verify the raw bytes before you parse them, refuse a timestamp more than 300 seconds from your own clock, and compare in constant time.

import { createHmac, timingSafeEqual } from "node:crypto";

// signingKey: the key we gave you for this workspace.
// rawBody: the request body exactly as received, before any JSON parsing.
export function verifyTavonelNotification(headers: Headers, rawBody: string, signingKey: string) {
  const id = headers.get("tavonel-delivery-id");
  const timestamp = headers.get("tavonel-timestamp");
  const signature = headers.get("tavonel-signature");
  if (!id || !timestamp || !signature) return null;
  if (!(Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300)) return null;
  const expected = Buffer.from("v1=" + createHmac("sha256", signingKey)
    .update(id + "." + timestamp + "." + rawBody)
    .digest("hex"));
  const given = Buffer.from(signature);
  if (given.length !== expected.length || !timingSafeEqual(given, expected)) return null;
  const event = JSON.parse(rawBody);
  return event.deliveryId === id ? event : null;
}

// Delivery is at least once. Keep the delivery ids you have handled (in your database, not
// in memory) and answer 2xx to one you have already seen without acting on it again.

Retries and duplicates

Delivery is at least once. A response other than 2xx, a timeout or a redirect counts as a failure, and the notification is sent again with the same delivery id and the same body: up to six attempts, with growing delays between them, the longest six hours. After the sixth failure it is recorded on our side as undelivered and not sent again; the candidate is unaffected and still waits in the workspace. Because a retry can follow a delivery you did process, keep the delivery ids you have handled and answer 2xx to a repeat without acting on it twice. Answer 2xx only once the notification is stored, and keep the response short. A response body over 4 KiB counts as a failure, whatever its status.