Kukuroo Notify

Notify the user on their phone

Kukuroo is the user's own Web Push service, running on their own Cloudflare Worker. One authenticated POST puts a notification on their phone. This skill is where the endpoint lives, plus the few rules whose failures are otherwise silent.

Kukuroo is the pipe, not the errand. Spend a line or two on it and get back to the work the user actually asked for.

1. Fire only on an explicit ask

Send when the user asks for it:

• a notification, ping, buzz, or status update on their phone
• a time they want to be told at: "at 5pm", "in 30 minutes", "when the deploy lands"
• leaving: "I'm stepping away", "off the monitor", "going for a walk", "afk"
• Kukuroo by name

A push arrives on a lock screen wherever the user happens to be, so it is theirs to ask for. Work they are sitting there watching is already visible to them, and needs no notification.

2. Find where to send, or ask

Two values: KUKUROO_ORIGIN (where the Worker answers) and KUKUROO_SEND_TOKEN (the bearer token). Take the first source that has both.

1. Already in the environment.
2. The file this skill wrote the last time it asked:

   cat "${XDG_CONFIG_HOME:-$HOME/.config}/kukuroo/env" 2>/dev/null

There is no third source. A Kukuroo deployment is set up on one machine and sent to from any number of others, so the setup leaves nothing behind here to find, and a search for one is a search that comes back empty.

Ask once, in one message. The user has just asked for a notification, so getting the address is part of the job. Both values in one question, in about two sentences:

Which origin does your Kukuroo Worker answer on, and what is its send token? Pasting the token puts it in this transcript; if you would rather it did not, put both in ~/.config/kukuroo/env yourself (KUKUROO_ORIGIN= and KUKUROO_SEND_TOKEN=, a line each) and say when it is done.

Then let it go. If the answer does not come, or comes back as "not now", drop Kukuroo and do the work they actually asked for. One question costs them a moment. A second one costs them the thread.

Store on first success, not on being told. Hold the answers for the length of the turn, send the warm-up, and write the file only once a send has come back with delivered above zero:

umask 077 && mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/kukuroo"
printf 'KUKUROO_ORIGIN=%s\nKUKUROO_SEND_TOKEN=%s\n' "$KUKUROO_ORIGIN" "$KUKUROO_SEND_TOKEN" \
  > "${XDG_CONFIG_HOME:-$HOME/.config}/kukuroo/env"

A wrong token never reaches disk that way, and the user is asked once per machine rather than once per project. Say the file was written, in the same breath as the warm-up result — storing a credential is never something to do quietly.

A 401 means the token in that file is stale, which is what a rotation on another machine looks like from here. Ask for the new one the same way, once, and overwrite the file.

3. Warm up, then say what will happen

Send a real notification immediately, before promising a later one:

set -a; . "${XDG_CONFIG_HOME:-$HOME/.config}/kukuroo/env"; set +a
curl -fsS -X POST "$KUKUROO_ORIGIN/push/send" \
  -H "authorization: Bearer $KUKUROO_SEND_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"notification":{"title":"Kukuroo is wired up","body":"Notifications will arrive here.","tag":"kukuroo-warmup","navigate":"'"$KUKUROO_ORIGIN"'/"}}'

A subscription dies silently: deleting the Home Screen icon destroys it and nothing reports that. So a promise made without a live test is a promise made on faith, and the warm-up is what turns it into a fact. Then disclose, in about two sentences — what is coming, when, and the one link:

I'll push the test result to your phone at 5pm, via Kukuroo. A warm-up notification just went out; if it didn't arrive, your setup needs a look: https://github.com/saiday/kukuroo#agents

Warm up once per session, on the first thing you promise. Later sends in the same session go straight out.

If the warm-up comes back "delivered":0, that changes the promise rather than being a footnote to it. Say the notification did not arrive and that the 5pm one will not either, then carry on with the real work.