How Neo remembers unfinished work

Constrained state

Conversation state stores buyer constraints, selected product/cart context, checkout progress, active goals, and the most recent grounded facts. Only allowlisted paths and operations can be applied. Every decision records previous and next state snapshots plus intents, entities, tools, and failure categories.

Goals and tool runs

conversation_goals preserves executable checkpoints and blockers across unrelated turns. conversation_tool_runs records planned, completed, blocked, or deferred tool progress for a decision and optional goal. Open goals hydrate the next turn from backend records.

AQ1 adds a shadow buyer-commerce goal plus lifecycle-aware accepted constraints, search and blocker outcomes, result references, and exact source-message/tool provenance. AQ2 can consume the latest grounded search outcome for feature-flagged read-only buyer discovery and records the accepted semantic delta or rejection reasons.

AQ3 decisions can additionally persist a versioned grounded response composition. Completed AQ4 resolves fresh session-bounded product, active-cart, order, and named seller workflow references. Tracking and support are parent-linked child goals. Structured seller checkpoints preserve pending verification, product drafts, and payout views across interruptions, but resume revalidates current ownership and restores UI context only: it cannot publish a product, start verification, change an order, message a customer, or queue money movement. Pending-action confirmation, secure tracking access, and the support pause remain authoritative. The operations-only exact-session trace shows redacted goals, checkpoint data, dependencies, facts, recovery, copy, and surfaces. Historical backfill still copies only exact recorded search outcomes and never invents old intent or composition. General compensation and complete legacy reply migration remain partial.

Digest-bound pending actions

stateDiagram-v2
  [*] --> Pending: canonical payload and summary
  Pending --> Executing: matching action ID and digest
  Pending --> Cancelled: buyer cancels
  Pending --> Expired: time limit
  Pending --> Invalidated: facts changed
  Executing --> Completed: domain transaction commits
  Executing --> Pending: safe recovery before write
  Completed --> [*]

Order placement, unpaid cancellation, and refund requests use action-specific identifiers and a SHA-256-bound canonical payload. Free-form agreement cannot execute them. Execution revalidates ownership and the exact price, stock, address, quote, order, or payment snapshot before writing.

Human support handoff

A direct request for a person creates one open support case per conversation, appends a bounded transcript, and stores a resume checkpoint plus an explicit automation scope. Routine support is reviewed in parallel while shopping, tracking, and seller work remain usable. Order-specific support pauses only its typed subject. Only mandatory risk, security, legal, or system holds pause the whole conversation and require an assigned administrator to release them.

Automatic high-risk and repeated-failure escalation plus external staff notification remain incomplete.

Evidence and tests

• src/conversation-state.ts
• src/conversation-goals.ts
• src/conversation-shadow.ts
• src/pending-actions.ts
• src/support.ts
• db/migrations/030_goals_tools_cart.sql
• db/migrations/031_support_cases.sql
• db/migrations/050_conversation_shadow_state.sql
• test/whatsapp.test.ts
• test/web.test.ts
• test/pending-actions.test.ts
• test/support.test.ts