06 / UNDER THE HOOD
Run, Wait, or Skip
Wawa turns WhatsApp conversations into tasks. It watches the chats you turn on, reads new messages and screenshots, and drafts tasks, questions and waits with links back to the messages they came from. The code is on GitHub.
Task analysis is the heavy part. One run can read each new screenshot, draft items with the triage prompt, check them against the evidence with the review prompt, then review candidates, waits and proposed completions. That’s a lot of model calls to spend on “ok”, “thanks” and a thumbs up.
So before any of that runs, Wawa now asks one smaller question: is this batch worth it?
Receiving a message is not running a model
The first step was pulling two things apart that used to be one. The commit that did it is called “Separate signed webhook receipt from debounced decision-gated task analysis”, and that’s the whole design in one line. The technical reference puts it more bluntly: “Receiving a message does not run Luna.”
OpenWA sends webhooks for message.received, message.sent, message.edited, message.revoked and session.status. Wawa checks the HMAC over the exact raw bytes before it parses anything:
const expected = Buffer.from(
'sha256=' + createHmac('sha256', this.store.webhookSecret()).update(raw).digest('hex'),
);
const actual = Buffer.from(signature);
if (actual.length !== expected.length || !timingSafeEqual(actual, expected))
throw new Error('Invalid webhook signature');
Then it deduplicates. OpenWA retries deliveries (Wawa registers its hook with retryCount: 5), so the same event can arrive more than once. The key is a hash of the session, the event name and the idempotency key, falling back to a hash of the raw body. It goes into a webhook_events table inside the same SQLite transaction that saves the message, so a retry either finds the row and stops or is the first one in.
Messages from activated chats are saved straight away, even in manual mode. Everything else is ignored. No model is involved yet.
A durable debounce
People don’t send one message. They send five in a row, then a screenshot, then “sorry, this one”. Running analysis on the first of those is wasteful and usually wrong.
In automatic mode each saved message pushes back a per-chat job. The job lives in a chat_jobs table with two times: due, when it should run, and first, when the burst started. Every new message moves due forward by the quiet period, but never past first + 180:
INSERT INTO chat_jobs VALUES(?,?,?,1,?,?)
ON CONFLICT(chat_id) DO UPDATE SET
due = min(excluded.due, chat_jobs.first + 180),
generation = chat_jobs.generation + 1, ...
The default quiet period is 45 seconds. With that default, a chat that never goes quiet gets a due time no later than three minutes after its first message; the scheduler may start it later. (The cap only applies when a later message arrives, so a quiet period set above 180 seconds still holds a single message for the full period.) Because the job is a row in SQLite and not an in-memory timer, a restart picks it up where it left off. The scheduler just reads the earliest due and sets one timeout for it.
There is no recurring poll of OpenWA. A history reconciliation runs at startup, on session status changes, on configuration changes and on explicit recovery, and that’s it.
The decision call
When a job comes due, and a decision connection is selected, Wawa builds a small state object and asks for one of three choices:
const criteria = {
run: 'Messages contain a new action, changed task requirements, source evidence, screenshot, completion report, or ambiguity that task analysis should resolve.',
wait: 'The sender explicitly indicates that more related detail or attachments are still coming. Wait briefly for that material.',
skip: 'Every new message is clearly irrelevant chatter, a greeting, or an acknowledgement. There is no task, completion, changed requirement, or new evidence.',
};
The instructions say to treat source text as untrusted evidence, to “prefer run whenever uncertain”, and not to evaluate or perform the tasks. The state is trimmed: each message body is cut to 3,000 characters, the batch is at most 80 pending messages plus 40 replies, and it includes up to 30 existing tasks for context plus seconds_waited.
There are three ways to answer it.
- Codex or an ordinary API connection. The prompt goes through the same
callModelpath as everything else, and the output has to matchgate-schema.json:choice,confidencefrom 0 to 1, andreason. - OpenAI Decisions.
POST /v1/decisionswithgpt-6-luna, onechoicequestion namedtriggerwith the three options as choices. - TypeSafe Jev.
POST /v1/systemone, with the same criteria as typed choice criteria underquestions.trigger.
The two native APIs are a good fit because the question really is a classification. I don’t have to ask for JSON and hope. Both requests are built from the same criteria object:
if (profile.provider === 'openai')
return {
url: profile.baseUrl.replace(/\/$/, '') + '/decisions',
body: {
model: profile.model,
input: JSON.stringify(state),
questions: [{ type: 'choice', name: 'trigger', instructions,
choices: Object.entries(criteria).map(([value, description]) => ({ value, description })) }],
},
};
return {
url: profile.baseUrl.replace(/\/$/, '') + '/systemone',
body: { model: profile.model, state: JSON.stringify(state),
questions: { trigger: { type: 'choice', instructions, criteria } } },
};
A native call has a 20 second timeout and refuses redirects. Each one, successful or not, is written to an ai_usage table with the purpose trigger decision and the token count if the provider returns one.
Biased towards run
A gate that drops a real task is worse than no gate. So most of the code around the call exists to turn “skip” or “wait” back into “run”.
if (
result.choice !== 'run' &&
(result.confidence < 0.75 ||
messages.some((m) => m.type !== 'text' || m.direction === 'outgoing'))
)
return { ...result, choice: 'run',
reason: 'Uncertain, outgoing, or attachment evidence needs the task model.' };
if (result.choice === 'wait' && elapsed >= 180)
return { ...result, choice: 'run', reason: 'The maximum three-minute wait has elapsed.' };
In full, the gate runs task analysis when:
- the confidence on a wait or skip is below 0.75,
- any message in the batch isn’t plain text, so a screenshot or other attachment always runs,
- any message is outgoing, because the owner’s own reply might be the thing that completes a task,
- a wait would push the burst past three minutes,
- the decision service refuses to classify the batch, which becomes
runwith confidence 0, - the call throws for any reason (no key, HTTP error, timeout, bad payload),
- the answer is skip, but the chat has an open wait and a new incoming message, which might be the reply being waited for.
A wait reschedules the chat for at most 15 seconds later, and never past the three minute cap. A skip marks only the evaluated batch processed. The messages stay saved, they just don’t produce task work.
The 0.75 cutoff is not tuned against anything. The same number gates automatic category changes later in the pipeline, and 0.95 is the bar for filtering out a candidate as clearly not a task. The docs call these thresholds provisional and say outright that they are “application policies, not claims that provider confidence is calibrated for your chats.” That’s the honest state of it.
Run now skips the gate
In manual mode webhooks keep saving messages, and nothing runs until you press Run now. In automatic mode Run now bypasses both the debounce and the gate. If you’re asking, you want the analysis. It still runs the candidate and completion reviews.
There’s an end-to-end test for exactly this path: “a saved webhook batch reaches the decision API first; skip avoids Luna and Run now bypasses the judge”. A fake decision API answers skip with 0.99 confidence, the test checks that the task model is never called, then presses Run now and checks that it is.
Trade-offs
- An extra call on every batch. Batches that need analysis now pay for the gate and the analysis. The bet is that a lot of chat traffic is chatter. I haven’t measured how much, or what the gate saves, so I won’t put a number on it.
- The cheap path can be wrong. A skip at 0.8 confidence on a text-only, incoming-only batch does drop that batch. The fallbacks narrow when that can happen. They don’t make it impossible.
- Confidence isn’t calibrated. Both providers return a number between 0 and 1. Nothing in Wawa checks that 0.75 from one means the same as 0.75 from the other.
- Three minutes is a guess. The cap keeps a chatty group from starving analysis. It also means a slow typist can get analysed before they finish.
- A fresh workspace uses Codex for the gate. The native decision APIs need their own keys, so out of the box the gate is a schema-validated prompt, not a dedicated classifier.
The shape I’d keep for anything like this: save first, decide later, and make every failure on the deciding side fall back to doing the expensive, correct thing.