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
agentTokenofruntime.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
fulltoken, everything but the tokens themselves, for a script or a device:wisp tokens create --name nightly --capability full; - a
runtoken, 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:3008by 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, withurl,token,pid,versionandkind: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, orhttp://127.0.0.1:3008through an SSH tunnel you open (ssh -N -L 3008:127.0.0.1:3008 you@server). Never send a token over plainhttpacross 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" }
externalKeyis your own id for the conversation. The first call creates the Session and answers201; every later call with the same key returns the same Session with200. 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.projectRootis the folder the agent works in for the whole life of the Session. See Deploying an agent.originisdesktop(the default),cli,telegram,slackorschedule. Sendcli: it keeps your Sessions out of Wisp Desktop's sidebar. It only affects listing, viaGET /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:
| Field | Meaning |
|---|---|
input | a 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, arguments | run a Skill the Session can see |
modelPreference | optional; 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 |
confirmationMode | optional; policy (the default) or interactive, which confirmationModes must allow (it does by default) — see approvals |
idempotencyKey | optional; makes a retry safe, see Runs and restarts |
wait | optional; true (the default) holds the connection, false answers 202 at once |
outputSchema | optional; a JSON Schema the answer must satisfy — see a structured answer |
maxTurns | optional; the most model calls the Run may make, after which it fails step_ceiling. Without it a Run has no such limit |
deliver | optional; { "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"] }
statusiscompleted,failedorcancelled. A failed Run has afailurewith areason(the list) and a message that never quotes the conversation.toolCalls[].argsis the redacted form from the audit, not the raw arguments.artifactsare the files the agent sent you with itsdeliver_filetool, 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 theindex-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
idempotencyKeycame 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'sstatusand, 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}/eventsstreams the answer as it is written, each tool call, the Prompts and the outcome;Last-Event-IDresumes after a dropped connection. See the Event stream.GET /v1/runs?status=parkedfinds 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 assettledAfternext time; leavesettledAfterout the first time.limitpages it as in the plain listing, andnextCursoris the next page'ssettledAfter. channeltakes onlylimitandsettledAfter: addingcursor,sessionId,statusororigin, or sendingsettledAfterwithoutchannel, is400.- A
runtoken reads only its own Channel's deliveries (another Channel is403), and never a Run anotherruntoken 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:
apiVersionis the revision of/v1the Runtime speaks, now2. 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.minClientApiis the oldest revision an adapter may be written for and still be served, now1. 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.
| status | what to do |
|---|---|
400 | the body or query is wrong, or names a folder or schema the Runtime refuses: fix the request, do not retry it |
401 | the token is unknown or revoked |
403 | the token may not do this, such as a run token naming a projectRoot, or the mode is outside confirmationModes |
404 | no such Session, Run or Prompt; a Project Session may need its folder named again |
409 | see Follow-ups and cancelling |
5xx, or no connection | the 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
projectRootis403) and starts Runs in those; - it lists and reads Sessions and their history, and sets a Session's Model Selection (a
PATCHthat changes anything else is403); - 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
approveordeny; - it reads and starts the speech model's install;
- it reads and starts the Runtime's update (
GETandPOST /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 telegramor--channel slackit may name adelivertarget, of that Channel only. Without--channel, a Run that namesdeliveris403; - with
--channelit also reads and sets the Auto Mode switch (GETandPUT /v1/settings/auto-mode). It is the whole Runtime's: let only your adapter's owner change it. Without--channel, both are403; - with
--channelit also readsGET /v1/billing/me, so a Run refusedquota_exhaustedwhile Runs are paid from the balance alone can namewisp 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 withoutauthoris 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.