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 model + tools"]
    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 model/tool turn is allowed, the host can intercept for:

  • invalid Twilio signatures
  • duplicate Twilio message SIDs
  • unknown-number signup redirects
  • 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, active assessment/task prompts, quiet-hours context, and typed tools for capture, lookup, benefits, resources, wiki retrieval, scheduling, and caregiver-loop tracking1. Wiki and resource knowledge are retrieved by tools from generated static bundles rather than pre-injected by a classifier domain. The model owns language and judgment; the harness owns deterministic gates, effect validation, reply judgment, and what can be committed or sent 2.

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, turn classification when present, evaluator decision, flags, tool calls, latency, tokens, and cost
  • log knowledgeGaps when low-confidence, quality-flag, or no-benefit-match signals require substrate follow-up
  • open safetyEvents or reviewQueue rows when the turn requires operator attention
  • 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 and split admin modules read-only operator triage, scoped actions, caregiver diagnostics, redaction, and proof/export paths
src/prompt.ts SMS style-guide contract injected into the default harness prompt
src/turn/evalTaxonomy.ts evaluator flag disposition, bench mapping, safety/review routing semantics
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/wiki.ts deployed wiki-card fetch/cache and wiki tool search over agent-index.json
src/resources.ts static resource bundle import and resource search for the resources tool
src/caregiverLoad.ts data helpers for caregiver-load context and opportunity derivation
src/turn/assessment.ts deterministic assessment answer capture and assessment-start staging
src/turn/effectValidation.ts validation/sanitization of model-requested effects
src/turn/careDomainHooks.ts Pi tool hook policy for consent, schedule, effect validation, and model feedback
src/turn/judge.ts reply preparation, assessment machine, evaluator flag gathering, disposition routing, repair, and postprocessing
src/harnessReplay.ts scenario replay adapter for tests and benchmark integration
src/policy.ts regulatory, consent, and crisis gates
src/context.ts active assessment/current-task lifecycle prompts, onboarding progress, SDOH/EMA loop prompts, and quiet-hours helper
src/model.ts Pi/provider wrapper, typed tools, proactive turns, compaction, and context transform
src/tools.ts caregiver-owned tool surface, including wiki/resources lookup and caregiver-loop tracking
src/evaluator.ts safety, quality, tool-grounding, low-confidence, and knowledge-gap signal checks
  • 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 -> ↩