Text reply goes live

00What we're building

Today, every inbound SMS goes to the legacy stateless text_agent (generates suggestions, optional auto-reply, no memory). This spike adds a parallel agentic path: a number assigned an ai_agent routes its inbound to a stateful, per-contact agent thread that holds conversation memory and acts with real domain tools.

01Decisions locked

Four product/architecture forks, resolved with you before planning.

02End-to-end flow

The reroute lives in handle_inbound_message (twilio_events_api.rs), at the point that today spawns the legacy text_agent.

03Schema & migrations

Three migrations. Columns first, then the seed (which depends on the columns existing). Schema files regenerate via just generate — never hand-edited.

04The Text Reply agent

A new platform system agent (org/user NULL), cloned per member so each member's threads run on their own owned agent — the owner's session is what grants the domain tools.

Configuration

Provisioning

Append TEXT_REPLY_AGENT_ID to DEFAULT_USER_AGENT_SOURCES ([Uuid; 3] → [Uuid; 4]) so new members get a clone at signup, and the seed migration backfills clones for existing members.

05Find-or-spawn helper

The reusable seam (shared with #1429's Scheduled trigger): one long-lived thread per (agent, contact), race-safe under concurrent inbound.

// src/mods/ai_agent/services/find_or_spawn_contact_thread_service.rs (new)
pub async fn find_or_spawn_contact_thread(
    db: &DatabaseConnection,
    agent_id: Uuid,
    contact_id: Uuid,
    payload: AiThreadEventPayload,   // event-type parameterized — InboundSms OR Scheduled
) -> Result<Uuid, AppError> {
    let key = format!("contact:{contact_id}");

    // 1. Reuse a non-archived thread for (agent, key) if one exists.
    if let Some(id) = active_thread_for(db, agent_id, &key).await? {
        enqueue_and_maybe_spawn(id, None, payload).await?;
        return Ok(id);
    }

    // 2. Else insert one WITH the correlation_key. The partial unique index
    //    uq_ai_thread_agent_correlation_active guards against a concurrent
    //    insert; on 23505 we re-query the winner's thread.
    let id = match spawn_ai_agent_thread(db, agent_id, Some(key.clone())).await {
        Ok(id) => id,
        Err(AppError::Database(e)) if is_unique_violation(&e) =>
            active_thread_for(db, agent_id, &key).await?
                .ok_or_else(|| AppError::Internal("race lost but no thread".into()))?,
        Err(e) => return Err(e),
    };
    enqueue_and_maybe_spawn(id, None, payload).await?;
    Ok(id)
}

06Suggest vs. send gate

The send_mode column swaps the agent's terminal move. Autonomous sends; suggest drafts pickable options. Both decided at the single non-assistant tool-build site.

// run_ai_agent_thread_service.rs — build_domain_tools_for_agent(&db, &agent, reply_ctx)
let mut tools = collect_agent_domain_rig_tools(&session, tier_flags);
match agent.send_mode.as_str() {
    "suggest" => {
        // Cannot send. Swaps send_sms for a draft-options tool bound to the inbound.
        tools.retain(|t| t.name() != "send_sms");
        if let Some(ctx) = &reply_ctx {
            tools.push(build_propose_sms_replies_tool(ctx.clone()));
        }
    }
    _ => /* autonomous: send_sms stays, curried to reply-from the texted number (§7) */ {}
}
tools

Suggest mode = pickable reply options (reuse the live picker)

The suggest agent's job is to draft, not send. Its terminal tool — propose_sms_replies(options: [2–3 strings]) — is built per-turn, curried with the inbound reply_ctx (contact_id, message_id) the way escalate_to_user is bound to its thread. It writes one row into the existing text_agent_suggestion table; from there the whole legacy surface wires up with zero new UI:

07Reply from the right number settled · curry

The verification's most important finding: send_sms resolves the from number from the member, not the number the contact texted.

Settled now that suggest mode forces the same plumbing: a ReplyContext { contact_id, message_id, phone_number_id } is extracted from the freshest InboundSms pending event and threaded into build_domain_tools_for_agent. It drives both terminal tools:

• autonomous — send_sms is curried so phone_number_id defaults to the texted line even if the model omits it (model can still override).
• suggest — propose_sms_replies is bound to (contact_id, message_id); the human's pick sends from the same line via the composer.

08Webhook reroute & safety gates

One branch in handle_inbound_message, plus three guards the verification flagged.

// twilio_events_api.rs — replaces the current legacy text_agent spawn (~line 265)
match phone.ai_agent_id {
    Some(agent_id) => {
        // gate 1: don't auto-engage an opted-out contact
        // gate 2: skip media-only / empty-body inbound (nothing to reason about)
        if opted_out || body_for_agent.trim().is_empty() {
            tracing::info!("agentic path skipped (opt-out or empty body)");
        } else {
            tokio::spawn(find_or_spawn_contact_thread(
                agent_id, contact_id,
                AiThreadEventPayload::inbound_sms(message.id, contact_id, phone.id, body),
            ));
        }
        // gate 3: legacy text_agent is NOT spawned for opted-in numbers (no reply race)
    }
    None => { tokio::spawn(handle_inbound_message_for_text_agent(/* unchanged */)); }
}

09InboundSms payload

A new enum variant. Verified blast radius: exactly two exhaustive match arms; every other read site deserializes and degrades gracefully.

// ai_thread_event_payload_type.rs
pub enum AiThreadEventPayload {
    UserMessage(AiThreadUserMessage),
    InboundSms(AiThreadInboundSms),          // NEW
}
pub struct AiThreadInboundSms {
    pub message_id: Uuid,
    pub contact_id: Uuid,
    pub phone_number_id: Uuid,   // the texted number → reply from here (§7)
    pub text: String,
}
// as_text() → &m.text (joins conversation history)
// page_context() → None (SMS has no app page)

The drained event's as_text() becomes the turn prompt via payload_text(); page_context()=None is safe (freshest_page_context uses find_map). The text may be wrapped with a one-line context preamble naming the inbound number so the model knows which line to reply from.

10Verification findings

A 15-agent workflow read the actual code and adversarially checked every load-bearing claim. Distilled — "confirmed" = design holds; "gap" = the plan now closes something it originally missed.

11Open questions for you

Two decisions left (Q2, Q3). Q1 settled itself once suggest mode required the same reply-context plumbing.

12Build order

Bottom-up: schema → payload → helper → gate → reroute → seed → tests. Each step compiles before the next.

1. 1Migrations: columnssmall

   phone_number.ai_agent_id + ai_agent.send_mode + text_agent_suggestion (make text_agent_id nullable, add ai_agent_id). Register in lib.rs, you run just generate.

2. 2InboundSms payloadsmall

   Variant + struct + inbound_sms() ctor + 2 match arms + round-trip tests.

3. 3spawn + find-or-spawnmedium

   Extend spawn_ai_agent_thread with correlation_key; new find_or_spawn_contact_thread + race-path test.

4. 4Reply context + send_mode gatemedium

   Extract ReplyContext from the freshest InboundSms; thread it into build_domain_tools_for_agent. Curry send_sms default-from; on suggest, drop send_sms. Unit test: suggest drops send_sms, autonomous keeps + curries it.

5. 5propose_sms_replies toolmedium

   New reply-context-bound tool: validate 2–3 options, insert a text_agent_suggestion row (ai_agent_id set). Added to suggest-mode turns. The existing panel/fetch/pick/send renders it — no UI work.

6. 6Webhook reroute + gatesmedium

   Branch on phone.ai_agent_id with opt-out / empty-body / text_agent-skip gates.

7. 7Seed Text Reply + clone fixmedium

   Constant, seed migration (mirrors drafter), DEFAULT_USER_AGENT_SOURCES, and the explicit send_mode copy in the runtime clone.

8. 8Verify + reviewsmall

   cargo check both targets, /review-code, manual inbound test (suggest + autonomous).

13Out of scope (noted in PR)

• follow-up issue Proactive "drafts are waiting" alert — push/in-app notification "{Agent} drafted N replies for {contact}" deep-linking to /messaging/{contact_id}, reusing the inbound-SMS notify path. This spike surfaces drafts in-conversation; the alert that pulls the user there ships next.
• defer Assignment UI — lands later in the agent view (assign numbers to this agent) + a set/list API with auth.
• defer Idle-TTL thread archival — a reaper cron. Threads stay long-lived; the existing 100-event history window bounds per-turn cost. Revisit with summarization.
• defer Per-contact behavior override — repurposing contact_text_agent stays a future seam (per-thread tool gating).
• defer send_mode toggle UI — set via DB for the spike; a per-agent control ships with the assignment UI.
• defer Media-aware turns — MMS-only inbound is skipped for now (gate 2) rather than fed to the agent.
• note Mid-turn batching — rapid inbounds collapse into the next turn. Pre-existing runtime behavior, no event loss; not re-architected here.

14Testing

Unit

• InboundSms serde round-trip; as_text() returns the body; page_context()=None.
• find_or_spawn: first call inserts; second reuses (no duplicate); simulated unique-violation re-queries the same thread.
• send_mode gate: suggest bundle excludes send_sms and includes propose_sms_replies; autonomous includes send_sms (curried) and not the propose tool; both include escalate_to_user.
• propose_sms_replies inserts a text_agent_suggestion row the existing get_suggestions_api returns.
• Clone preserves send_mode='suggest' (guards the §3 correctness bug).

Manual (acceptance criteria)

• Set phone.ai_agent_id; inbound with no thread spawns one keyed contact:{id}; follow-up reuses it.
• autonomous agent replies via send_sms from the texted number; suggest agent drafts 3 options that appear on the message (tap → send), and does not send on its own.
• Non-opted-in number still uses legacy text_agent — no regression.
• Opted-out / media-only inbound does not spawn a turn.