lilith-platform.live/codebase/@features/quinn-ai

quinn.ai

LLM gateway and engine control dashboard. Lives at quinn.ai.apricot.lan (dev) and quinn.ai.transquinnftw.com (prod).

Auth via SSO — same login as quinn.my.

---

Navigation

Sidebar on the left. Top item is Conversation (collapsible, shows per-agent sub-items). Everything else is a flat nav link.

---

Pages

/ — Conversation

The AI assistant. Full streaming chat with tool use and context cards.

• Agent selector — each agent in the sidebar sub-list has a different system prompt and model. Switch mid-session; conversation resets.
• Chat feed — streaming NDJSON; tool calls and results surface inline.
• Context panel (right side) — structured cards pushed by the assistant (tasks, platforms, schedule, info, warning). Updated as the assistant runs tools.
• Pane layout — conversation list pane on the left of the chat (toggleable). Shows prior sessions.
• Voice — TTS playback via @speech-synthesis MCP. Toggle in the toolbar.
• Message composer — supports text + image attachments.

Assistant tools the LLM can call during a session:

• add_recurring_cost — log a recurring expense
• analyze_image / describe_image / generate_image — vision and image generation
• get_platform_stats — follower counts and platform status
• save_content_task — add a task from chat
• list_calendar_events(from?, to?) — iCloud events, default next 14 days
• list_tour_legs — private city visits with revenue targets and status
• list_tour_stops — public tour announcements (transquinnftw.com/tour)

Context injected passively into every session (no tool call needed):

• Vigil phase + daily task count
• Pending tasks
• Engine mode
• Upcoming calendar events (next 7 days) — shown in the schedule card and system prompt
• Recent outreach engine events

Assistant tools the LLM can call during a session:

• — log a recurring expense
• / / — vision and image generation
• — follower counts and platform status
• — add a task from chat
• — iCloud events, default next 14 days
• — private city visits with revenue targets and status
• — public tour announcements (transquinnftw.com/tour)

Context injected passively into every session (no tool call needed):

• Vigil phase + daily task count
• Pending tasks
• Engine mode
• Upcoming calendar events (next 7 days) — shown in the schedule card and system prompt
• Recent outreach engine events

---

/messages — Messages

Read-only mirror of Quinn's iMessage threads via the mac-sync service.

Note: mac-sync v2 is bidirectional across all surfaces. iMessage send goes via the legacy POST /admin/send-queue/enqueue (table macsync.send_queue), while mail / calendar / reminder / note sends go via per-module POST /admin/{module}-send-queue/enqueue endpoints.

• Left pane: searchable conversation list sorted by last message
• Right pane: thread view with sent/received bubbles
• Data polled from /api/messages → mac-sync → chat.db

Use this to find thread context before generating a draft or recording a correction.

---

/drafts — Engine Drafts

Side-by-side view of what the engine drafted vs what Quinn actually sent. Refreshes every 5s.

Summary bar — total / paired count / pairing rate / breakdown by source, mode, classification.

Patterns card (collapsible) — correction counts per CoT step with recent examples. Expand to see which reasoning step is failing most. Feeds the MCP list_correction_patterns tool.

Filters — source, mode, classification, handle, paired/unpaired.

Draft cards — each card shows:

• Handle + badges (source, mode, classification)
• Inbound trigger (or "proactive" if VIP touchpoint)
• Engine draft body
• Quinn's actual reply (green, when paired) + Δlen diff + Δt

CoT brief panel — expand toggle per card (only shown if draft_brief is populated). Shows position, chase, voice register, sanity issues, discovered thread facts from the 6-step reasoning pass.

Correction form — "Record correction" button on every card. Expands inline:

• Text area for Quinn's actual text
• Step selector (THREAD_FACTS · QUINN_STATE · THREAD_POSITION · CHASE_CHECK · SANITY_CHECK · VOICE_REGISTER)
• Optional reason
• Submits to POST /api/engine-drafts/:id/correction → quinn.api

Corrections power the quinn-drafts MCP feedback loop.

---

/engine — Engine Config

Two sections:

Facts DB — key/value store for persistent agent context (e.g. Quinn's current rate, city, availability). Search, add, delete entries. Used by the assistant to answer questions without hallucinating.

Agent Model Table — per-agent model assignments. Shows which Claude model each agent uses; editable.

---

/engine-mode — Engine Mode

Controls the auto-respond engine's fire behavior. Four modes:

Mode	Behavior
auto-fire	Engine sends automatically on eligible inbounds
draft-only	Engine generates drafts but routes all to Quinn approval
monitor-only	Engine logs events, no sends or drafts
off	Engine completely disabled

Requires a reason string when changing mode. Change is written to quinn.api and mirrored to the engine's local config file. Last-changed timestamp and author shown.

Use draft-only during testing or when fine-tuning drafts. Use auto-fire only when confident in the pipeline.

---

/outreach — Outreach Events

Raw event log from the auto-respond engine (outreach.event_log table). Shows the last 100 events by default, filterable by since.

Useful for debugging: see why a specific inbound was blocked (auto_respond_blocked), what template was selected, whether pre-fire checks passed, and what draft was proposed for Quinn's approval.

Event types:

• inbound_received — engine saw a new iMessage
• auto_respond_eligible / auto_respond_blocked — eligibility result + which check failed
• auto_respond_scheduled — template selected, send queued with pacing tier
• auto_respond_pre_fire — pre-fire 5-check gate result
• reply_proposed — Quinn-review draft sent to her self-notify
• self_notify_sent / self_notify_failed — delivery status

---

/templates — Templates

Library of auto-respond template strings. Each template has an ID, body, and conditions for when it's selected. Editable inline.

---

/timers — Timers

Scheduled one-shot or recurring actions. Create timers with a delay + action (send message, trigger nudge, etc.).

---

/nudges — Nudges

Proactive outbound rules. Each nudge has a trigger condition (time window, prospect state) and a message template. Separate from VIP touchpoints.

---

/personality — Personality

System prompt editor for each agent. Changes take effect on the next conversation session.

---

/block-list — Block List

Phone numbers blocked from auto-respond. Add/remove handles. Synced to the engine's block-list.json via quinn.api.

---

/tour-planner — Tour Planner

Upcoming city visits with date windows. Used to populate quinn_state.planned_locations_next_14d for the draft pipeline and to answer availability questions.

---

/experiments — A/B Experiment Dashboard

Tracks prospect outreach experiments from the prospect_experiments table.

• Summary bar — conversion rates per variant (total sent, converted count, rate%)
• Converted outcomes — replied_warm, yes_booking_intent, booked, session_happened
• Filter row — by variant, outcome (including "pending" for null), handle
• Experiment cards — handle, variant, score@send, tier@send, outcome badge, days silent, created timestamp
• Outcome color coding — converted = green, declined/no_reply = dim, pending = yellow
• Refetches every 30s
• Data from GET /api/experiments → proxied to /assistant/experiments on quinn.api

---

/prospects — Prospect Scores

ML scores from prospect-classifier-claude. Populated by running the classifier pipeline against active handles.

• Summary bar — total prospects, scored count, average score, HOT/WARM/COLD breakdown (HOT≥70, WARM 40-69, COLD<40)
• Filter row — status dropdown, min/max score, handle search
• Prospect cards — handle, score badge (green/yellow/red/grey), status, award tags (green chips), penalty flags (red chips), classifier reasoning note, last updated
• Score badge colors: ≥70 green, 40-69 yellow, <40 red, null grey
• Data from GET /api/prospects → proxied to /admin/clients?provider=quinn on quinn.api

---

/approvals — Draft Approvals

Web interface for the iMessage-based draft approval flow. The engine sends a self-notify to Quinn's phone with proposed options; this page shows pending proposals and lets her approve from the browser.

• How it works — clicking Approve sends "1 [ref:XXXX]" via mac-sync to Quinn's self-handle, triggering the existing reply-parser-loop. No new state machine.
• Warning banner — the quinn_approved → scheduleSend linkage is incomplete: messages get marked approved in outreach.prospect_state but the scheduled-send fire is not yet wired. Status is visible in the UI.
• Summary — pending count, resolved today count
• Proposal cards — handle, intent hash, reason routed to Quinn, time since proposed, TTL remaining, status badge
• Action buttons (pending only) — Option 1, Option 2 (if available), Skip, custom edit + Send
• After action: immediate refetch
• Refetches every 10s
• Data from GET /api/proposals → queries outreach.event_log + outreach.prospect_state

---

Draft feedback loop (Drafts page & Approvals page → MCP)

The fastest iteration path:

1. Open /drafts, filter classification=QUINN_REVIEW, find a bad draft
2. Note the draft ID from the card
3. In a Claude session on apricot with the quinn-drafts MCP: record_correction(draft_id=..., quinn_text="...", cot_step_failed="CHASE_CHECK")
4. After several corrections: list_correction_patterns() — see which step is failing
5. propose_prompt_revision(cot_step="CHASE_CHECK") → review suggestion
6. apply_prompt_revision(...) → write to prompts.py
7. draft_message(request={...}) — verify the fix on a representative thread

Alternatively, use the /approvals page as a web interface to approve or reject proposed drafts directly from the browser instead of relying on the iMessage self-notify flow.

---

Environment

Var	Purpose
VITE_SSO_URL	SSO base for logout redirect
QUINN_API_BASE_URL	quinn.api URL (backend-api → quinn.api proxy)
QUINN_API_SERVICE_TOKEN	Service token for quinn.api calls
MAC_SYNC_URL	mac-sync URL for iMessage thread reads. v2 routes: /client/imessage/* for reads + send-queue polling (Mac side); /admin/<module>-send-queue/* for write-back queueing; /my/<module>/* for read APIs.
AI_CORE_URL	AI Core URL for proposeReply calls
QUINN_OUTREACH_DB_URL	Postgres for outreach event log
QUINN_API_URL + QUINN_API_SERVICE_TOKEN	Engine → quinn.api for engine_drafts records