Skip to content

Data Agent SMS Runtime (Convex code)

GiveCare reference note for the hard-cut Greenfield SMS runtime across ../gc-sms/domain/, ../gc-sms/agent/, ../gc-sms/convex/, ../gc-sms/knowledge/, ../gc-sms/README.md, ../gc-sms/CODEMAP.md, and ../gc-sms/docs/. Current-tense runtime claims should use those files only; the retired BrownZip runtime exists in git history, not in the active tree.

Key information used in wiki

  • The current backend is a compact SMS-first Convex service. Its canonical durable-table inventory is convex/schema.ts, with a human-readable map in CODEMAP.md.
  • The live schema is grouped around identity and consent, channel ownership, active conversations, turn phases, message ledgers, typed memories, caregiver-owned loops, assessment/score proof, append-oriented events, and queued transport work.
  • The core flow is turns.receive -> durable caregiver/channel/conversation setup -> inbound message/turn insert -> evaluateGate -> deterministic boundary commit or Pi scheduling.
  • The active Twilio path is convex/http.ts -> convex/transport.ts -> convex/turns.ts. Twilio-specific client and signature code lives in convex/twilio.ts and convex/twilioSignature.ts.
  • The active Pi path is convex/mira.ts -> turns.reserveForAgent -> context.assembleForMira -> agent/piRunner.ts -> turns.commitAgentReasonResult, turns.routeToReview, or turns.failAgentTurn.
  • The commit boundary is convex/turns.ts:commitReasonResult. It validates the final reply, re-checks channel consent before enqueueing an outbound reply, commits only validated intents, records commit.result, and leaves review, proof, learning, and safety signals in the events substrate.
  • Follow-up requests become caregiver-owned loops only after commit validates their reason, consent basis, bounded due time, and observed consent. Delivery is handled by convex/followups.ts and the transport outbox.
  • Wiki-owned runtime knowledge is consumed from generated static artifacts under ../gc-sms/knowledge/generated/: benefits, resources, strategies, reviewed knowledge, and manifest provenance. knowledge/catalog.ts is the runtime catalog; knowledge/toolAdapters.ts shapes bounded evidence, and agent/tools.ts exposes those in-process lookups to Pi. They do not make a Convex query round trip.
  • Outbound delivery uses the outbox pattern: commit writes an outbox row, convex/transport.ts claims and marks queued SMS work, and Twilio callbacks reconcile provider status.