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. In the Greenfield runtime, the journey is a harness-owned kernel: inbound, gate, context, reason, commit1.

Current Greenfield runtime vs archive

Older wiki text described the archived BrownZip src/ runtime, scheduler, and richer journey-phase contract as live. The current backend is the Greenfield domain/, agent/, convex/, and knowledge/ runtime in gc-sms; the retired runtime exists in git history only14.

Caregiver-facing flow

sign up -> name who you care for -> six-question baseline -> understand the pressure
        -> get help with one need -> try one step -> consented check-back -> remeasure or close

A current need, safety concern, STOP, PAUSE, or HELP can interrupt at any point. GiveCare keeps useful context and the assessment checkpoint, helps with the immediate need, then returns without restarting intake. A low domain reading may lead to four focused questions after an ordinary support turn and explicit MORE assent; that focused check is not scheduled on a cadence.

Live Message Flow

flowchart TD
    A["Twilio inbound"] --> B["Signature validation"]
    B --> C["transport.handleIncomingMessage"]
    C --> D["turns.receive"]
    D --> E["Durable caregiver/channel/conversation/turn"]
    E --> F{"Domain gate"}
    F -->|Boundary| G["Boundary reason result"]
    F -->|Allow| H["Schedule mira.runTurn"]
    H --> I["reserveForAgent"]
    I --> J["context.assembleForMira"]
    J --> K["Pi Agent Core + tools"]
    K --> L{"Final result valid?"}
    L -->|No| M["routeToReview / fail"]
    L -->|Yes| N["commitAgentReasonResult"]
    G --> O["commitReasonResult"]
    N --> O
    O --> P["Outbox row or suppress/block"]
    P --> Q["transport.sendQueuedSms"]
    Q --> R["Twilio 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
  • STOP / HELP / SHARE regulatory commands
  • paused, stopped, or safety-hold channel states
  • identity-uncertain messages that need review
  • 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 ordering23.

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 turn1:

  • regulatory command replies and consent updates
  • explicit crisis and high-risk distress replies
  • channel blocks for stopped, paused, safety-hold, or identity-uncertain states

Pi branch

If no policy gate resolves the turn, the host builds context and calls the model with the current caregiver state, selected memories, open loops, channel constraints, source constraints, and typed tools for benefits, resources, guidance cards, strategies, and final structured output1. Knowledge comes from generated static bundles under gc-sms/knowledge/generated/, adapted by knowledge/catalog.ts; there is no live Convex resource table. The model owns language and judgment; the harness owns deterministic gates, validation, commit, transport, and proof 1.

Commit-Time Side Effects

Every live turn resolves through convex/turns.ts:commitReasonResult or a terminal review/failure path1. The commit boundary can:

  • insert or suppress an outbound reply through outbox
  • apply approved ordinary-sensitivity memory writes
  • open, close, block, or dismiss caregiver-owned loops
  • start or complete assessment runs and write score snapshots
  • record safety, review, knowledge-gap, opportunity, proof, and learning signals as events
  • mark the turn committed or review

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 create loops only after commit validates the reason, consent basis, observed consent, bounded future dueAt, and stop condition. convex/followups.ts later converts due loops into follow-up turns, and convex/transport.ts sends queued SMS through the outbox.

Live State Axes

The current runtime uses compact durable state rather than the archived v1 journeyPhase enum1. These fields are not the whole journey map; they are small pieces of durable reality the service can safely store and re-derive from.

State field Values Purpose
turns.phase received, reasoning, committed, review, failed processing state for a single inbound turn
channelStates.consentState unknown, active, paused, stopped, safety_hold per-channel consent and safety gate
channelStates.replyConsent / followupConsent / proactiveConsent unknown, allowed, blocked send-class permission for inbound replies, follow-ups, and proactive sends
loops.status open, closed, dismissed, blocked, expired caregiver-owned follow-up or load-loop state

Nearby memories, assessmentRuns, scoreSnapshots, and events carry the detailed facts and proof surfaces. A caregiver may still have compatibility fields such as phase, loopStage, and activatedAt, but public journey prose should not treat those as the live orchestration contract.

Runtime Ownership Boundary

This page explains the public shape of the SMS journey. It does not own the runtime file map. Exact owner surfaces, code paths, and proof commands live in gc-sms (README.md, CODEMAP.md, docs/service-blueprint.md, docs/architecture.md, docs/domain-contract.md, docs/convex-runtime.md, and docs/verification.md). When this public explanation drifts from the backend, update gc-sms first and keep this page as a summary.

  • Backend — current v2 schema groups, commit boundary, and scheduler model
  • Mira — caregiver-facing product behavior and one-next-step posture
  • Assessments and GiveCare Score — public explanation of measurement and score snapshots
  • Crisis Routing — safety tier details and crisis semantics

  1. GiveCare. "GC-SMS Runtime Contract." Exact verified Hound owner projection. Source -> ↩↩↩↩↩↩↩↩

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

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

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