Skip to main content

The adapter contract

An adapter is your code that connects Wisp to the outside world: a chat bot, a webhook handler, a scheduler. Wisp ships a few of its own — schedules, a Telegram bot and a Slack app — and they use this same contract. Anything else is yours to write: Wisp runs when it is called, one Run at a time, and returns the result.

That keeps an adapter small. It translates three things:

a conversation → a Session (looked up by your own key)
a message → a Run
the Run's answer → whatever you send back

Your side keeps the bot token, polling or webhooks, deduplication, timers, retries, and sending messages. Wisp's side keeps the Session and its history, connectors, Rules, the audit, and one answer per Run.

Connecting​

Every request but a tokenless GET /v1/health carries Authorization: Bearer <token>:

  • the one token, the agentToken of runtime.json, which reaches everything. On a machine where Wisp inside Hermes is set up it changes at every Hermes start, so a script or a device that keeps a copy takes a named token instead;
  • a named full token, everything but the tokens themselves, for a script or a device: wisp tokens create --name nightly --capability full;
  • a run token, made for an adapter, which reaches only what an adapter needs (see Tokens for an adapter).

The base URL is where the Runtime listens:

  • On the same machine, http://127.0.0.1:3008 by default. A script there reads the address and the one token from $WISP_HOME/runtime.lock, exactly as the CLI does. It is a JSON file, readable only by its owner, with url, token, pid, version and kind:

    URL=$(jq -r .url ~/.wisp/runtime.lock)
    TOKEN=$(jq -r .token ~/.wisp/runtime.lock)
  • From another machine, the https:// address of the TLS proxy in front of it, or http://127.0.0.1:3008 through an SSH tunnel you open (ssh -N -L 3008:127.0.0.1:3008 you@server). Never send a token over plain http across a network. See Remote access.

The full API, with request and response schemas, is served at GET /v1/openapi.json. The CLI is tested against it, so it is a good source for generating a client.

A first automation​

With URL and TOKEN set as above, five requests cover the whole contract. Check that the Runtime is up and signed in; status must be ready (login_required means run wisp login first):

curl -fsS -H "Authorization: Bearer $TOKEN" "$URL/v1/health"

Open a Session. Without projectRoot it works on a Desk:

SESSION=$(curl -fsS -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "origin": "cli", "externalKey": "first-automation", "title": "first automation" }' \
"$URL/v1/sessions" | jq -r .id)

Run a turn and wait for its answer:

curl -fsS -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "input": "Say hello in three languages." }' \
"$URL/v1/sessions/$SESSION/runs" | jq -r .output.text

Or start it without waiting, and follow its answer as it is written. Each Event is one data: line of JSON; the stream closes after run.completed, run.failed or run.cancelled:

RUN=$(curl -fsS -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "input": "Now in three more.", "wait": false }' \
"$URL/v1/sessions/$SESSION/runs" | jq -r .runId)
curl -fsSN -H "Authorization: Bearer $TOKEN" "$URL/v1/runs/$RUN/events"

A tool the Rules hold for a person is refused in such a Run. To answer it yourself instead, send "confirmationMode": "interactive": the Run parks and the answer lists its confirmations, each answered with POST /v1/runs/{runId}/confirmations/{id} and { "decision": "approve" } or deny (see Approvals).

The same from the CLI is wisp run, wisp run --detach, wisp runs events and wisp confirm; see Using the CLI from scripts.

One conversation is one Session​

POST /v1/sessions
Authorization: Bearer <token>
Content-Type: application/json

{ "projectRoot": "/srv/agents/incidents",
"origin": "cli",
"externalKey": "incident:4711",
"title": "incident 4711" }
  • externalKey is your own id for the conversation. The first call creates the Session and answers 201; every later call with the same key returns the same Session with 200. You do not need a table that maps your chats to Sessions. A key always points to the same Session; to start a conversation over, use a new key. At most 256 characters, so hash anything longer.
  • projectRoot is the folder the agent works in for the whole life of the Session. See Deploying an agent.
  • origin is desktop (the default), cli, telegram, slack or schedule. Send cli: it keeps your Sessions out of Wisp Desktop's sidebar. It only affects listing, via GET /v1/sessions?origin=.

A Session without projectRoot works on a Desk, a folder of its own; see Sessions and Projects.

Naming the Project again​

The Runtime keeps Sessions in memory and finds a Desk Session again on its own, but it does not remember which folder a Project Session's Project is in. Once it has dropped such a Session from memory, after a restart for instance, the Session's routes answer 404 unless the request names the folder again in the query:

POST /v1/sessions/{id}/runs?projectRoot=/srv/agents/incidents

PATCH /v1/sessions/{id}, POST /v1/sessions/{id}/runs, POST /v1/sessions/{id}/cancel and POST /v1/runs/{runId}/retry need it then. GET /v1/sessions/{id} and GET /v1/sessions/{id}/history take it too, but without it still answer, from the stored rows, the first with projectRoot: null. A wrong folder is the same 404, never another Session. On PATCH, the query's projectRoot finds the Session and the body's is the Project being added. The CLI always sends the folder it runs in. Calling POST /v1/sessions again with the same externalKey and projectRoot loads the Session as well. An adapter that always sends the same projectRoot never meets the 404.

A message is a Run​

POST /v1/sessions/{id}/runs
Content-Type: application/json

{ "input": "grafana: latency p99 back under 400ms for 10 minutes",
"idempotencyKey": "incident-4711:evt-8824" }

The connection stays open until the Run ends — or send "wait": false and get 202 { runId, status } at once, then read the Run with GET /v1/runs/{runId} or follow its Events (see Not waiting). The body takes exactly one of input or skill:

FieldMeaning
inputa string, or an array of content blocks (text, image_url, file, pdf_text, document, audio). Every block takes an optional author: owner (the default) or third_party — see Who wrote what. A document block (filename, mediaType, base64 data) is a file's bytes: the Runtime reads a PDF, a .docx, a .xlsx, a .pptx or any text file as its text, so the adapter needs no parser. An audio block (mediaType, base64 data) is OGG/Opus, MP3 or WAV; the Runtime transcribes it on its own machine before the turn, detecting the language among 25 European ones (the list is in the block's schema)
skill, argumentsrun a Skill the Session can see
modelPreferenceoptional; a model id from GET /v1/models, or tier:<name>, for this Run only. Without it the Run follows the Session's Model Selection, then the Runtime Default — see the model
confirmationModeoptional; policy (the default) or interactive, which confirmationModes must allow (it does by default) — see approvals
idempotencyKeyoptional; makes a retry safe, see Runs and restarts
waitoptional; true (the default) holds the connection, false answers 202 at once
outputSchemaoptional; a JSON Schema the answer must satisfy — see a structured answer
maxTurnsoptional; the most model calls the Run may make, after which it fails step_ceiling. Without it a Run has no such limit
deliveroptional; { "channel": "telegram" | "slack", "externalKey": "…" }, the chat the outcome goes to — see delivering an outcome

The answer is one JSON object:

{ "runId": "…",
"status": "completed",
"output": { "text": "Latency has recovered…\n\nDraft for #ops: …" },
"toolCalls": [ { "name": "mcp__telegram__get_messages", "args": {}, "ok": true, "durationMs": 380 },
{ "name": "mcp__telegram__send_message", "args": {}, "ok": false, "durationMs": 1 } ],
"usage": { "inputTokens": 8122, "outputTokens": 311, "totalTokens": 8433 },
"artifacts": ["notes/4711.md"] }
  • status is completed, failed or cancelled. A failed Run has a failure with a reason (the list) and a message that never quotes the conversation.
  • toolCalls[].args is the redacted form from the audit, not the raw arguments.
  • artifacts are the files the agent sent you with its deliver_file tool, relative to the Session's folder (its Project, or its Desk when it has none), with forward slashes, in the order delivered. A file it only wrote is not listed: ask for the file in the input ("send me the CSV") and the agent delivers it. GET /v1/runs/{runId}/artifacts/{index} answers the index-th one's bytes, to send on as a file.

A structured answer​

Send a JSON Schema as outputSchema and the outcome carries the agent's answer as output.structured, already validated against it, beside output.text with the last thing the agent said in words:

{ "input": "triage incident 4711",
"outputSchema": {
"type": "object",
"properties": {
"severity": { "enum": ["low", "high", "critical"] },
"summary": { "type": "string" } },
"required": ["severity", "summary"],
"additionalProperties": false } }
{ "runId": "…",
"status": "completed",
"output": { "text": "Done.", "structured": { "severity": "high", "summary": "…" } },
… }

The agent ends the Run by handing over a value; one that does not satisfy the schema is returned to it with the reasons, and it tries again; stopping without one, it is reminded. After five such attempts the Run fails with failure.reason output_schema_unsatisfied. A Run that reaches its maxTurns first still fails step_ceiling. The value is in the waited-on answer, in the terminal Event and on GET /v1/runs/{runId}. It works with input or skill, in either Confirmation Mode, waited on or not.

The schema's root must be "type": "object". For a list or a single value, wrap it in one property:

{ "type": "object",
"properties": { "items": { "type": "array", "items": { "type": "string" } } },
"required": ["items"] }

A schema the Runtime cannot take is refused 400 before the Run starts: one that does not compile, a remote $ref (nothing is ever fetched), a format the validator does not know (it would check nothing), pattern or patternProperties (a regular expression runs inside the Runtime, and a slow one would stall it), a schema above 64 KiB, or a root other than an object.

A refused tool is not a failed Run​

Nobody approves tool calls during a Run in the default mode, policy, so a tool without a Rule that allows it is refused (see Permissions). The agent is told and continues, usually by drafting what it was not allowed to send. The refused call appears in toolCalls with ok: false, and the Run still completes.

Design your adapter around this: Wisp drafts, your adapter sends.

Approvals​

With confirmationMode: interactive, a tool the Rules hold for a person does not fail: the Run parks, and the waiting request answers at once:

{ "runId": "…",
"status": "parked",
"confirmations": [ { "id": "…", "toolName": "mcp__telegram__send_message",
"toolCallId": "…", "args": { "…": "…" } } ] }

args is what the desktop's approval card shows, the recipient named by Wisp where a connector names one. agentId names the subagent that asks, when one does. A Prompt with "askedEveryTime": true is one no Rule can lift, such as a file tool reaching outside the folder: offer approve or deny only, since allow_project and allow_global approve it and write no Rule. Answer each Prompt with POST /v1/runs/{runId}/confirmations/{id} and { "decision": "approve" } (or deny, allow_project, allow_global). That request waits for the Run's next park or its end and answers like the first one did; while another Prompt of the same step is still pending, it answers at once with the Prompts left. A Prompt nobody answers within confirmTimeoutMs is denied and the Run goes on. A Prompt already settled, or one that is not this Run's, is 404; read the Run with GET /v1/runs/{id}, which lists a parked Run's confirmations.

An approval may carry text, which replaces the draft the Prompt offered before the tool runs: { "decision": "approve", "text": "…" }. It counts on the tools whose card has a text to edit — Gmail's send_email (the body) and the Telegram connector's send_message, reply_to_message, edit_message and save_draft (the text) and send_file (the caption) — and is ignored elsewhere. A text the tool's own input rules refuse fails that call.

The same Prompts go out on the Run's Event stream as confirmation.required, and each settles there as confirmation.resolved with how: api, timeout or cancel. So the answer can come from whoever follows the stream, while the first request still waits; the first answer settles a Prompt, and that waiting request then returns. An answer with "wait": false returns 202 at once. A Prompt of a subagent arrives and is answered exactly like one of the main agent.

The operator decides whether any of this is possible: a Run naming a mode outside confirmationModes is refused 403. The default allows both; an operator who sets the list to ["policy"] turns Prompts off.

Follow-ups and cancelling​

A Session runs one Run at a time. A message that arrives while a Run is going waits in a queue, and its connection stays open while it waits. You do not have to serialise anything yourself.

409 Conflict on a new Run means one of these:

  • the Session's queue is full (maxQueuedRunsPerSession, 10 by default): back off, or drop the message;
  • the same idempotencyKey came with a different request. The error names the key;
  • the key's message is already in the Session but its Run's record is gone, or the record lost its outcome: the message may have acted, so it is never run again.

POST /v1/sessions/{id}/cancel stops the current Run and everything queued behind it. It answers 202 when something was stopped and 204 when nothing was running. You cannot cancel a single queued message. A Run parked on a Prompt is cancelled too: its Prompts are denied, and the waiting request answers cancelled.

DELETE /v1/sessions/{id} is 409 while the Session has a Run going: cancel first, then delete.

Not waiting​

A caller that cannot hold a connection — a serverless function, a queue worker, a CI step behind a proxy — sends "wait": false. Then:

  • GET /v1/runs/{runId} gives the Run's status and, once it ended, the same outcome a waited-on Run answers with. It reads the Run's record, so it works after a restart too.
  • GET /v1/runs/{runId}/events streams the answer as it is written, each tool call, the Prompts and the outcome; Last-Event-ID resumes after a dropped connection. See the Event stream.
  • GET /v1/runs?status=parked finds Runs waiting on a person, across Sessions, when you kept no ids of your own.

A repeat with the same idempotencyKey answers 202 with the same runId and its status now, and starts nothing. Nothing is pushed to you: there are no webhooks — poll the Run or follow its Events.

Delivering an outcome​

A Run can name the chat its outcome belongs in with deliver: a Channel, telegram or slack, and the chat's key, the same key wisp schedules create --deliver takes:

{ "input": "…", "deliver": { "channel": "telegram", "externalKey": "telegram:123456789", "label": "DM with @anna" } }

label, optional and up to 200 characters, is the chat's name as you see it ("Wisp team", "#ops"). It is kept with the Run only, never with a job the Run makes, and Wisp Desktop shows the newest one a chat was sent with, from GET /v1/delivery-targets.

The Runtime sends nothing itself. The Channel's adapter, such as the Telegram bot, polls the Runs addressed to it and posts each one:

GET /v1/runs?channel=telegram&settledAfter=<cursor>
  • It lists only Runs that have ended, oldest first by the order they ended in, from every entrance, schedules included. A Run whose answer begins or ends with a line [SILENT] is left out.
  • Each Run carries settleCursor. Keep the last one you posted and send it as settledAfter next time; leave settledAfter out the first time. limit pages it as in the plain listing, and nextCursor is the next page's settledAfter.
  • channel takes only limit and settledAfter: adding cursor, sessionId, status or origin, or sending settledAfter without channel, is 400.
  • A run token reads only its own Channel's deliveries (another Channel is 403), and never a Run another run token started.

A Run's deliver shows on GET /v1/runs/{runId}, and a Run a schedule fired carries the job's name as schedule.

From TypeScript​

There is no SDK package to install: generate the types from the API of the Runtime you run, and call it through openapi-fetch. The document is the one GET /v1/openapi.json serves; every release also carries it as v1.json beside its archives.

npm init -y && npm pkg set type=module && npm install openapi-fetch
curl -fsS -H "Authorization: Bearer $TOKEN" "$URL/v1/openapi.json" -o v1.json && npx openapi-typescript v1.json -o v1.d.ts

A Run started without waiting, its answer followed as it is written. Save it as call.ts and run it with WISP_URL=$URL WISP_TOKEN=$TOKEN npx tsx call.ts:

// A typed call to the Wisp Runtime through `openapi-fetch`, with the types
// `openapi-typescript` generates from the release's v1.json into `./v1.d.ts`.
import createClient from "openapi-fetch";
import type { paths } from "./v1.js";
import { runEvents } from "./events-reader.js";

const baseUrl = process.env.WISP_URL ?? "http://127.0.0.1:3008";
const token = process.env.WISP_TOKEN ?? "";
const client = createClient<paths>({ baseUrl, headers: { authorization: `Bearer ${token}` } });

const session = await client.POST("/v1/sessions", { body: { origin: "cli", title: "Nightly report" } });
if (!session.data) throw new Error(`session: HTTP ${session.response.status}`);

const run = await client.POST("/v1/sessions/{id}/runs", {
params: { path: { id: session.data.id } },
body: { input: "Summarise yesterday's incidents", wait: false },
});
if (!run.data) throw new Error(`run: HTTP ${run.response.status}`);

for await (const event of runEvents(baseUrl, token, run.data.runId)) {
if (event.kind === "text.delta") process.stdout.write(event.text);
if (event.kind === "run.completed") console.log(`\n${event.outcome.usage.totalTokens} tokens`);
}

The Event stream is the one part a generator does not handle. This reader, saved as events-reader.ts beside v1.d.ts, follows a Run's Events until the terminal one, skips a kind it does not know, and resumes with Last-Event-ID a dropped connection or one a proxy answers 5xx or 429, as a Run waiting on a Prompt is not over; an optional signal stops it, so a process shutting down is never held by a Run it follows. It runs server-side, on Node 18 or later: a browser's EventSource cannot send the token.

// Reads a Run's Events from the Wisp Runtime. Server-side: the stream needs the
// Bearer token, which a browser's EventSource cannot send. `./v1.js` holds the
// types `openapi-typescript` generates from the release's v1.json.
import { setTimeout as sleep } from "node:timers/promises";
import type { paths } from "./v1.js";

export type RunEvent =
paths["/v1/runs/{runId}/events"]["get"]["responses"]["2XX"]["content"]["text/event-stream"];

// Every kind this reader knows, and whether it ends the stream. Any other kind is skipped.
const KINDS: Record<RunEvent["kind"], boolean> = {
"run.queued": false, "run.started": false, "run.parked": false, "run.resumed": false,
"text.delta": false, "audio.transcribed": false, "tool_call.started": false, "tool_call": false, "gap": false,
"confirmation.required": false, "confirmation.resolved": false,
"question.required": false, "question.resolved": false,
"run.completed": true, "run.failed": true, "run.cancelled": true,
};

function decode(data: string): RunEvent | undefined {
try {
const event: unknown = JSON.parse(data);
const known = typeof event === "object" && event !== null && "seq" in event &&
typeof event.seq === "number" && "kind" in event && typeof event.kind === "string" &&
Object.hasOwn(KINDS, event.kind);
return known ? (event as RunEvent) : undefined; // the Runtime vouches for the rest
} catch {
return undefined;
}
}

// Follows a Run's Events until its terminal one. A connection that drops, or
// ends having brought an Event, is resumed after the last seq with Last-Event-ID;
// one refused, as while the Runtime restarts, or answered 5xx or 429, is tried again each second.
// `signal` stops it: following a Run never holds a caller that is shutting down.
// `after` resumes a Run already followed past that seq.
export async function* runEvents(
baseUrl: string, token: string, runId: string, signal?: AbortSignal, after?: number,
): AsyncGenerator<RunEvent> {
let lastSeq = after;
for (let progressed = true; progressed; ) {
progressed = false;
let res: Response;
try {
res = await fetch(`${baseUrl}/v1/runs/${encodeURIComponent(runId)}/events`, {
headers: {
authorization: `Bearer ${token}`,
...(lastSeq === undefined ? {} : { "last-event-id": String(lastSeq) }),
},
signal,
});
} catch (err) {
if (signal?.aborted) throw err;
progressed = true; // the Runtime is down: tried again a second later, for as long as it is
await sleep(1000, undefined, { signal });
continue;
}
// A proxy's 5xx or a 429 is not the Run's end: it may wait on a Prompt. Only a 4xx is.
if (res.status >= 500 || res.status === 429) {
await res.body?.cancel();
progressed = true;
await sleep(1000, undefined, { signal });
continue;
}
if (!res.ok || !res.body) throw new Error(`events: HTTP ${res.status}`);
let buffered = "";
try {
for await (const chunk of res.body.pipeThrough(new TextDecoderStream())) {
buffered += chunk;
for (let end = buffered.indexOf("\n\n"); end !== -1; end = buffered.indexOf("\n\n")) {
const data = buffered.slice(0, end).split("\n").find((l) => l.startsWith("data: "))?.slice(6);
buffered = buffered.slice(end + 2);
const event = data === undefined ? undefined : decode(data);
if (event === undefined) continue; // a `: ping`, an unknown kind or a broken frame
lastSeq = event.seq;
progressed = true;
yield event;
if (KINDS[event.kind]) return;
}
}
} catch (err) {
if (signal?.aborted) throw err;
progressed = true; // the connection dropped: resume, a second later
await sleep(1000, undefined, { signal });
}
}
throw new Error("events: the stream ended before the Run did");
}

Both are checked against each release's document before it ships. A Runtime that adds an Event kind fails to typecheck against this reader until the kind joins its table, so the compiler tells you what is new.

Health​

GET /v1/health with the token returns the Runtime's state (ready, login_required and so on; see Troubleshooting), its version and kind, apiVersion and minClientApi, and update when a newer release exists. Without a token it still answers 200 with an empty object, which is enough for a liveness probe. GET /v1/ready answers whether the Runtime will accept a Run right now.

Two numbers tell an adapter whether it and the Runtime fit:

  • apiVersion is the revision of /v1 the Runtime speaks, now 2. It goes up with every change a client may come to rely on, a new route or field included. When it is lower than the one your adapter was written for, the Runtime is too old: ask its owner to update it.
  • minClientApi is the oldest revision an adapter may be written for and still be served, now 1. It goes up only when a route or field is removed or renamed or changes meaning. When your adapter's revision is lower, the adapter is too old: update the adapter.

While a newer release exists, every answer to a request that carries a token also carries an X-Wisp-Update header naming its version. An adapter can offer to install it with POST /v1/update and read how it ended with GET /v1/update once the Runtime is back, as the Telegram bot and the Slack app do. See updating the Runtime.

Errors​

An error answers a JSON body { "error": "…" }, a sentence for a person. Some carry a code beside it for a program to match, such as confirmation_mode_interactive_not_allowed; match the status and the code, never the sentence.

statuswhat to do
400the body or query is wrong, or names a folder or schema the Runtime refuses: fix the request, do not retry it
401the token is unknown or revoked
403the token may not do this, such as a run token naming a projectRoot, or the mode is outside confirmationModes
404no such Session, Run or Prompt; a Project Session may need its folder named again
409see Follow-ups and cancelling
5xx, or no connectionthe Runtime is down or restarting: wait for GET /v1/health to say ready, then send the same request with the same idempotencyKey

A Run that failed is not an HTTP error: it answers 200 with status: "failed" and a failure.reason.

Tokens for an adapter​

Give each adapter its own run token instead of the one token, so a leak costs only that adapter and wisp tokens revoke shuts it out alone:

wisp tokens create --name my-bot --capability run

A run token reaches only what an adapter needs:

  • it opens Sessions on the Desk only (a projectRoot is 403) and starts Runs in those;
  • it lists and reads Sessions and their history, and sets a Session's Model Selection (a PATCH that changes anything else is 403);
  • it reads the model catalog and the Runtime Default, but does not set the Runtime Default;
  • it reads Runs, their Events and artifacts, and cancels a Session's Runs;
  • it answers only the Prompts of Runs it started, with approve or deny;
  • it reads and starts the speech model's install;
  • it reads and starts the Runtime's update (GET and POST /v1/update), which installs only the newest signed release. Each start restarts the Runtime and its adapter services, and a retry after a failure downloads the release again: let only your adapter's owner start it;
  • with --channel telegram or --channel slack it may name a deliver target, of that Channel only. Without --channel, a Run that names deliver is 403;
  • with --channel it also reads and sets the Auto Mode switch (GET and PUT /v1/settings/auto-mode). It is the whole Runtime's: let only your adapter's owner change it. Without --channel, both are 403;
  • with --channel it also reads GET /v1/billing/me, so a Run refused quota_exhausted while Runs are paid from the balance alone can name wisp billing topup. It changes nothing in billing. The balance is the owner's: do not post it to a shared chat.

Everything else (Rules, connectors, schedules, tokens) is 403. Only the one token makes, lists and revokes tokens. A revoked token is 401 from its next request on, and the jobs its bot made in a chat are paused.

Not available yet​

There are no webhooks: the Runtime never calls your adapter. Poll GET /v1/runs/{runId} or follow its Events instead.

Who wrote what​

Wisp strips control characters, invisible characters and its own framing tags from every connector result, so a tool's output cannot pretend to be part of the conversation's structure. What Wisp cannot know is who wrote a piece of text; only the connector or the adapter knows that.

  • In input, mark a message you relay from someone other than the account owner with "author": "third_party". The agent then reads it as data, never as an instruction. A block without author is the owner's own words.
  • In a connector, the Telegram connector marks every message with fromMe. If you write MCP servers, mark authorship the same way, as a field next to the text, so the agent can tell an instruction from a quote of one.

A scheduler is an adapter too​

A scheduled job should create a fresh Session each time it fires; a cron job is not a conversation. Name each Run after the moment it was scheduled for:

# every 15 minutes. \% escapes the % that crontab would otherwise eat.
*/15 * * * * cd /srv/agents/queue && ~/.wisp/bin/wisp run "check the queue and report anything stuck" --key "queue-check:$(date -u +\%Y-\%m-\%dT\%H:\%M)"

That line is the whole scheduler. wisp run without a Session starts one in the current folder, waits, prints the answer and exits 0 or 1. Because --key is the job name plus the scheduled minute, a job that fires twice for the same minute joins the first Run instead of starting a second.

Scheduled Runs are often the longest a machine does. Make sure a restart's drain window covers them; see Runs and restarts.

Next: the incident bot, the whole contract as something you can run.