roost-client (TypeScript)

Report any AI agent into Roost with one small client. Heartbeat while alive, a run per task, an approval before anything you can't undo.

npm install roost-client

import { Roost } from "roost-client";

const roost = new Roost({
  url: process.env.ROOST_URL!,        // https://xxxx.supabase.co
  apiKey: process.env.ROOST_API_KEY!, // from Roost → Settings → API keys
  slug: "inbox-triage",
});

// 1. Register on boot (idempotent)
await roost.register({
  name: "Inbox Triage",
  jobTitle: "Email triage",
  department: "Ops",
  runtime: "nanoclaw",
  monthlyBudgetUsd: 50,
});

// 2. Heartbeat while alive
const stopHeartbeat = roost.startHeartbeat(15_000);

// 3. A run per task
const run = await roost.startRun({ trigger: "cron" });
try {
  // ... do the work ...
  await roost.log("Sorted 38 emails", { run });
  await roost.endRun(run, { status: "success", costUsd: 0.12, summary: "Sorted 38 emails" });
} catch (err) {
  await roost.endRun(run, { status: "error", errorMessage: String(err) });
}

// 4. Gate anything irreversible behind a human
const ok = await roost.requestApproval({
  actionLabel: "Send 240 outreach emails",
  payload: { count: 240 },
});
if (ok) {
  // ... a human clicked Approve in the dashboard ...
}

stopHeartbeat();

Notes

• No dependencies. Uses global fetch and crypto.randomUUID (Node 18+, Deno, Bun, browsers).
• Telemetry never crashes your agent. Pass onError to swallow transport errors instead of throwing.
• requestApproval blocks (polls the approval endpoint) until a human decides, it expires, or timeoutMs elapses. It returns true only on an explicit approve.
• url accepts either the project URL or the full …/functions/v1 base.

MIT.