Build notes › topic

AI & agents

What it takes to put a language model in front of real customers in a WhatsApp thread: what it is allowed to say, what it is allowed to do, how it is stopped from answering on top of a colleague, and what it does when it should not answer at all.

Covered here: Cloudflare Workers AI · 24-hour service window · 7-star customer experience · agent decision tree · agentic tool use · AI permissions · allow-list enforcement · Cloudflare D1 · consent keyword collision · conversation transcript ordering

• 19 August 2026 · AI architecture & safety

  Klaros Chatbot As-Is AI Architecture: Fail-Closed Design and Zero-Token Grounding

  A first-hand developer perspective on our existing WhatsApp chatbot architecture. Outlines our choices behind the "Rules First, LLM Tail, Human Override Always" priority tree in agent-decision.mjs, human staff takeover yield, fact-fenced auto-responder in ai-auto-reply.mjs, zero-token learned answers cache in learned-answer.mjs ($0 token cost), pure JS BM25 retrieval in retrieve.mjs, and D1 token cost accounting.

• 19 August 2026 · updated 21 August 2026 · AI architecture & roadmap

  Klaros WhatsApp Autonomous AI Agent: To-Be Architecture for a 7-Star Experience

  A candid developer architectural roadmap challenging our own past design decisions, now carrying a correction. The hybrid sparse-dense retrieval this note proposed had already been written and registered ahead of every other strategy, and it had never executed once: the Cloudflare Vectorize binding it depended on does not exist on the worker, so every request took its fallback branch and re-served plain BM25 while reporting success. The audit that found it also found the real defect, which was more mundane and worse: ingest deletes the 173 question-and-answer pairs the site publishes in its own structured data, then asks a ranking function to reconstruct them from the prose. Dense retrieval is deferred in favour of contextual BM25 and reranking.

• 15 August 2026 · agentic design

  The WhatsApp assistant that could explain booking but not book

  At 13:00 we shipped a screen that cross-references what our assistant can explain against what it can actually send. It reported scheduling as explainable and not sendable. At 13:56 somebody typed “Book a meeting for me” and was told a person would pick it up, while a working scheduler sat one function away. No corpus entry fixes that: a request for an action is not a question. What closed it, why the enforcement lives in an allow-list rather than the prompt, and the shadowed question that would have denied a feature we had shipped four hours earlier.

• 13 August 2026 · conversational AI

  The WhatsApp auto-reply that answered a hello with a price list

  A contact of five weeks typed “Hello” and received an explanation of our licensing. The model was not hallucinating: the thread query selected the oldest 40 rows of a 46-message conversation, so it was shown messages 21 to 40 and never saw the greeting it was answering. Every timestamp had been stripped too, so a pricing exchange from three weeks earlier read as the previous turn. Investigating one bad reply surfaced seven more ways the same assistant was failing to listen, including voice notes answered with total silence, “cancel my order” recorded as an unsubscribe, and a customer who asked to speak to a person and was ignored twice.

• In progress

  The half of a sale that nobody demos

  Every platform shows you the payment landing. Almost none show you the twenty minutes afterwards: who gets told, who packs it, what the buyer hears while they wait, and what happens when it ships four days later and the messaging window has closed.

• In progress

  Where the ask ends and the shop begins

  A payment request is messaging machinery. A product library is a commerce application, and the part most likely to be replaced by a real one. On finding that seam in our own code, and making it a documented extension point instead of a function that happened to sit in the middle of a file.

• In progress

  What a feature looks like when nothing consumes it

  Contact limits computed on every request and enforced nowhere. A tier ladder that is marketing copy at runtime. On the difference between building a capability and shipping one, found in our own codebase.