How Neo understands a message

Planner contract

The OpenAI Responses API returns a strict structured proposal: role context, intents, entities, confidence, missing information, constrained state changes, required tools, reply mode, proposed action, and an AQ2 semantic turn delta. The delta names dialogue acts, a buyer-discovery or public group-deal goal operation, constraint operations, a bounded outcome reference, and clarification intent. The response is validated and normalized before it can influence state. Backend grounding gives public group-deal language its own intent, semantic goal, and typed read instead of treating it as generic catalogue search.

The planner is an interpreter. It cannot write the database, reserve inventory, confirm payment, promise delivery, or authorize a refund.

Typed tool plan

flowchart LR
  Message[Buyer message] --> Planner[Structured proposal]
  Planner --> Normalize[Validate and normalize]
  Normalize --> Compile[Backend tool compiler]
  Compile --> Reads[Authorized read tools]
  Reads --> Facts[Grounded facts]
  Compile --> Gate[Pending action gate]
  Gate --> Action[One authorized action]
  Facts --> Reply[Purpose-specific reply]
  Action --> Reply
  Compile --> Blocker[Explicit blocker]
  Blocker --> Reply

CONVERSATION_TOOL_REGISTRY declares read/action kind, dependencies, authorization, and idempotency. Backend-owned requirements supplement planner output for order status, privacy intake, and digest-bound order/remedy confirmation.

Facts and blockers

Read tools return typed facts for catalogue results, exact product details, inventory, seller reputation, and buyer-owned order status. Missing, unauthorized, or failed requirements produce blockers; the response cannot infer successful execution from a handler result shape.

Delivery answers fail closed without an exact address and current quote. Payment status comes from stored provider-confirmed state. Catalogue availability comes from published, active, in-stock backend results.

Clarification and recovery

A complete product request is searched even at moderate confidence. Low confidence asks a question only when the product identity is genuinely unresolved or the buyer expresses uncertainty. Obvious spelling mistakes may be corrected; uncertain corrections receive one targeted question.

With the AQ2 feature flag enabled, neo-dialogue-policy-v2 validates read-only buyer discovery and authenticated order tracking. Discovery keeps the grounded constraint/outcome rules; tracking is limited to the buyer_order_tracking goal, no shopping constraints, and get_order_status. Consequential turns remain outside this policy.

AQ3 independently gates neo-grounded-response-v5. It binds recommendations and group deals to registered reads, checkout guidance to current cart/pending-action/tool facts, tracking results to a typed verified-buyer fact whose actor and order buyer IDs match, and support copy to the exact automation scope. Missing or denied tracking reads disclose no order facts. Purpose, facts, recovery, next step, copy, and the actual WhatsApp surface are recorded without changing confirmation or action authorization.

Verification

Deterministic planner, policy, composer, compiler, authorization, and transcript tests form the normal gate. The 12-turn benchmark exercises the real isolated WhatsApp/database/catalogue path and asserts persisted evidence plus a zero-write boundary. AQ0–AQ6 are complete. AQ5 stores one redacted integrity-hashed replay envelope per normal decision; ai:replay:conversation uses SELECT-only export and offline validation/diff. neo-conversation-tools-v23 covers every supported WhatsApp buyer and seller read/action boundary. neo-conversation-candidate-adapter-v21 replays exact frozen results with zero database reads, writes, or provider calls. Governance and buyer actions require HMAC-attested result evidence bound to the exact decision, message, session, and actor; seller actions require independently loaded durable receipts plus authority and checkpoint/fulfilment bindings. Authorization, result, receipt, session, actor, subject, and redaction tampering fail closed. The final AQ6 audit inventories discovery, group deals, cart/checkout, tracking/remedies/reviews, privacy/support, registration/catalogue/publication, orders/fulfilment, payouts/protected handoff, customers/follow-up, and every named resume path.

Risk grading always selects corrections, repeated failures, low-confidence consequential turns, financial workflows, and support escalation while deterministically sampling ordinary turns. Atomic job claims plus attempt, provider-call, and estimated-cost ceilings bound execution. Human-approved suggestions alone enter regression intake, where the validated redacted replay through the reviewed decision is materialized as a versioned deterministic fixture and exportable bundle. The protected read-only conversation-quality dashboard reports loops, stale constraints, failed no-result recovery, corrections, tool/provider errors, overdue support SLA, escalation eligibility, grading state, alerts, and first-failure-layer clusters.

• db/migrations/054_conversation_replay_envelopes.sql
• db/migrations/055_conversation_quality_grading.sql
• src/whatsapp.ts
• src/conversation-policy.ts
• src/conversation-response.ts
• src/conversation-plan.ts
• src/conversation-state.ts
• src/conversation-replay.ts
• src/conversation-replay-runtime.ts
• src/conversation-candidate-capture.ts
• src/conversation-review.ts
• src/conversation-quality-operations.ts
• scripts/replay-conversation.ts
• scripts/conversation-quality-ops.ts
• test/conversation-policy.test.ts
• test/conversation-replay.test.ts
• test/conversation-review.test.ts
• test/conversation-quality-operations.test.ts
• test/assistant-quality-benchmark.test.ts
• test/whatsapp.test.ts