Skip to content

SMS Journey

The live SMS journey is the path from a Twilio inbound message to a committed turn outcome and any resulting outbound SMS or follow-up job. In v2, the journey is a harness-owned pipeline: policy gates first, then context, model, evaluator, and commit12.

Current v2 runtime vs archived v1

Older wiki text described the archived v1 journeyPhase and sms/turns/* runtime as live. The current backend uses caregivers.phase plus caregivers.loopStage, with the turn path centered on convex/agent.ts and the v2 harness files in src/25.

Live Message Flow

flowchart TD
    A["Twilio inbound"] --> B["Signature validation"]
    B --> C["agent.ingestInbound"]
    C --> D{"Known caregiver?"}
    D -->|No| E["Signup redirect"]
    D -->|Yes| F["Persist inbound message"]
    F --> G["Enqueue inbound job"]
    G --> H["processDueJobs"]
    H --> I["agent.runTurn"]
    I --> J{"Policy gate match?"}
    J -->|Regulatory / consent / crisis| K["Deterministic reply"]
    J -->|No| L["Build context"]
    L --> M["Run Pi/Gemini"]
    M --> N["Evaluate reply + effects"]
    K --> O["Commit turn"]
    N --> O
    O --> P["Pending outbound SMS"]
    P --> Q["Twilio send + status callback"]

What Happens Before The Model

The model is not the first thing that owns an inbound message1. Before a Pi/Gemini turn is allowed, the host can intercept for:

  • invalid Twilio signatures
  • duplicate Twilio message SIDs
  • unknown-number signup redirects
  • before-reply domain, risk, urgency, and missing-context classification
  • chief-of-staff brief derivation from classifier labels
  • STOP / HELP / SHARE regulatory commands
  • pending-consent YES handling before START handling
  • START resubscribe handling
  • pending, revoked, or expired consent
  • crisis, passive-death, burnout-escape, or isolation safety patterns

Crisis handling preempts ordinary support logic, consistent with ADR-0001, the SMS reply constraints, and the runtime's safety-first ordering34.

Deterministic Branch vs Pi Branch

Deterministic branch

The host keeps a deterministic path for cases where compliance or safety should not depend on a general model turn2:

  • regulatory command replies and consent updates
  • consent-pending, revoked, or expired replies
  • explicit crisis and high-risk distress replies
  • first consent grant from a pending caregiver

Pi branch

If no policy gate resolves the turn, the host builds context and calls the model with the current caregiver state, recent messages, selected memory, resource context, care guidance, a classifier-derived chief-of-staff brief, classifier-selected caregiver skill guidance, and typed tools1. The brief names the caregiver's operational priority, the caregiver need, any recipient risk, the memory to use or capture, and the required one-next-step rule. Pi/Gemini owns language and judgment; the harness owns what can be written and sent.

Commit-Time Side Effects

Every live turn resolves through convex/agentDb.ts:commitTurn1. That mutation can:

  • insert the pending outbound message
  • apply approved memory writes, superseding prior singleton keys when needed
  • record a traces row with mode, classifier labels, evaluator decision, flags, latency, tokens, and cost
  • open a safetyEvents row when the turn requires human review
  • mark the current job complete

This is why the practical unit of SMS orchestration is a committed turn outcome, not just text returned by the model.

Approved follow-up requests are enqueued immediately after commit through convex/scheduler.ts, keeping quiet-hours, consent, retry, and lock handling in the scheduler rather than inside the persistence mutation.

Live State Axes

The current runtime uses two caregiver state axes rather than the archived v1 journeyPhase enum2.

State field Values Purpose
phase onboarding, active, paused, crisis broad caregiver lifecycle and safety state
loopStage consent, profile, active compact harness stage for consent, initial profile collection, and ongoing support
consent pending, granted, revoked, expired TCPA consent gate and audit timestamps

Nearby memory keys such as profile:*, care:*, eligibility:*, and assessment:* carry the detailed facts; the phase fields stay deliberately small.

File Ownership

File / area Responsibility
convex/http.ts Twilio webhook signature validation, status callback, signup/admin HTTP routes
convex/agent.ts inbound ingestion and policy -> context -> model -> evaluate -> commit turn flow
convex/scheduler.ts async job queue, quiet-hours deferral, outbound rate checks, retry state
convex/agentDb.ts caregiver/message/memory/job queries and atomic commitTurn mutation
convex/outbound.ts pending outbox send through Twilio
convex/admin.ts harness health and production-flow reports for flags, failure modes, outbox, jobs, and safety events
src/styleGuide.ts SMS style-guide contract injected into the default harness prompt
src/failureTaxonomy.ts maps evaluator flags to gc-bench failure mode IDs for harness health reports
src/memoryKeys.ts shared memory-key contract for tools, scoring, benefits, and context
src/memory.ts memory sensitivity, merge semantics, normalization, and derived facts
src/turn/pipeline.ts pure policy-gate order and post-model post-processing
src/turn/classifier.ts before-reply domain, risk, urgency, and missing-context labels
src/turn/chiefOfStaff.ts domain-to-brief contract for caregiver priority, caregiver need, recipient risk, memory use/capture, and the one-next-step rule
src/turn/harnessReplay.ts seed-scenario replay for product-QA harness tests, including deterministic replies, injected model runners, chief-of-staff brief injection, scenario-specific autofail checks, and postprocess memory/profile effects
src/policy.ts regulatory, consent, and crisis gates
src/context.ts context bundle, chief-of-staff brief injection, memory selection, quiet-hours helper
src/skills.ts caregiver-specific skill-pack contract injected into context by classifier domain
src/model.ts Pi/Gemini agent wrapper, typed tools, proactive turns, compaction
src/evaluator.ts pre-commit safety, length, clinical-claim, benefits/legal certainty, tone, boundary, caregiver-first posture, one-next-step, specificity, classifier-aware escalation, and write filters
  • Backend — current v2 schema groups, commit boundary, and scheduler model
  • Crisis Routing — safety tier details and crisis semantics

  1. GiveCare. "Data Agent SMS Runtime (Convex code)." Source -> ↩↩↩↩

  2. GiveCare. "SMS Journey Orchestration Contract." Source -> ↩↩↩↩

  3. GiveCare. "Crisis Gate Ordering." Source -> ↩

  4. GiveCare. "SMS Mira Soul." Source -> ↩

  5. GiveCare. "GiveCare Backend Specification." Source -> ↩