# Karma Subito AI Guru

> Written for: engineers working on Console 2 / core.

Internal concierge-support agent inside Console 2. A concierge chats with an
ElevenLabs agent (text-only) that diagnoses member issues through Core and
Viewpoint APIs, proposes fixes a human must confirm, and keeps three records
in step: the local ticket, a ClickUp task, and a Viewpoint member log.

- Product spec: `subito-ai-guru-meeting-notes.md` (repo root, kept local — deliberately untracked)
- Visual spec: `docs/console/DESIGN_SYSTEM.md`
- Agent system prompt (paste into the ElevenLabs dashboard):
  `docs/subito-ai-guru-system-prompt.md`
- E2E runbook (executable curl scenarios): `docs/subito-ai-guru-e2e.md`

**Status: feature-complete on `feature/subito-ai-guru`, 150 passing vitest
cases, E2E-verified against local connectors. Local only — not pushed.**

---

## 1. Architecture

```
Concierge (Console 2, /admin/guru)
  │ cookie session + RBAC
  ▼
core /v1/admin-console/guru ──── tickets, sessions, confirms, allowlist,
  │                              audit, analytics, attachments, transcripts
  │ mints signed URL (xi-api-key never leaves the server)
  ▼
ElevenLabs agent (text-only WebSocket chat)
  │ server tools (webhooks)                 │ post-call webhook (HMAC)
  ▼                                         ▼
core /v1/guru/tools/* ─ read-only      core /v1/kevo/webhooks/post-call
  diagnosis + propose-action             routed by agent_id → guru-postcall
                                         BullMQ job → ClickUp + Viewpoint
```

**The security invariant — writes never flow through the LLM.** The agent's
only write tool is `guru_propose_action`, which creates a PENDING card
(server-built wording, 15-min expiry). Execution happens exclusively on the
authenticated console session (`POST /actions/:id/confirm`) after a
server-side **edit-allowlist** check against the session user. A forged or
injected tool call can at worst create a card nobody unauthorised can
confirm. Refusal wording is fixed by spec:
"Sorry, you don't have permission to update this member's information."

**Tool authorization is two-layered:** the `X-Guru-Secret` workspace secret
proves the call comes from our agent; `conversation_id` (bound to
`system__conversation_id` — the LLM cannot write it) must map to a ticket a
concierge opened, which also yields the acting concierge for audit.

**Conversation ↔ ticket binding:** opening a chat creates a `GRU-` ticket and
mints the signed URL; the client reports the conversation id back
(`POST /tickets/:ref/conversations`) — a client can only bind to its own
ticket; binding to a closed ticket reopens it.

## 2. Agent tools (registered by `src/cmd/guru-setup.ts`)

| Tool | Purpose | Key input |
|---|---|---|
| `guru_lookup_member` | Member + registration state (Viewpoint vs app), account type/status, `member_record_id`, `profile_id`; by membership number also `existing_cases` (open console cases for the member — duplicate detection) | one of email / membership_number / member_number |
| `guru_member_overview` | Last app session (app, version, device) + booking counts | membership_number |
| `guru_bookings` | Recent Viewpoint bookings (live Viewpoint DB) | membership_number |
| `guru_booking` | One booking | booking_number |
| `guru_points` | Points balance | membership_number |
| `guru_entitlements` | Contracts (validity/expiry, inventory type, fee_paid) + points entitlement lines across ALL clubs (`clubResortID 0` — verified authoritative 13 Nov 2026 vs member 905167; per-club calls can miss the member's real club). Product-matrix flags still escalate. Contract CRMData (card numbers, prices) is hard-excluded | membership_number |
| `guru_availability` | Per-unit nightly inventory (Viewpoint categorycounts) + the rule that blocks: resort_closure / blackout (resorts table periods, incl. RECURRING_ANNUAL wrap) / booking_horizon (2y) / no_inventory; lists active hot deals with `tier_restricted`; `within_90_days` fact. Member-tier pricing rules not evaluated | resort_code, arrival, departure, unit_code? |
| `guru_submission_log` | App/website booking_requests (member DB) correlated with Viewpoint via ext_booking_id: created on hold / referenced booking missing / never became a booking. No free text or contact columns | membership_number, from?, to? |
| `guru_external_booking_status` | Karma-side view of exchange bookings (RCI / Weekly Escapes / 7Across / Getaways markers in bookingsource/type/channel): presence, status, dates, amount+currency. Vendor-side state always escalates (no vendor API) | booking_number OR membership_number (+from/to) |
| `guru_ticket_history` | Ticket state + ClickUp comments (reopen context) + `other_cases_for_member`; cannot search ClickUp itself | — |
| `guru_update_ticket` | Classify/annotate ticket (categories: login, bookings, points, entitlements, fees, other) | category, summary, member_ref |
| `guru_propose_action` | Propose PASSWORD_RESET / SEND_VERIFICATION_EDM / SYNC_PROFILE / RESEND_RCI_CONFIRMATION_EDM — never executes | per-type id field |

All tool args are zod-validated and treated as untrusted; responses are
whitelisted DTOs (that is the PII mask — emails/phones masked, nothing
leaves unless named), 15s timeout, agent-readable plain JSON.

## 3. Write actions (executors)

| Action | Executor | Notes |
|---|---|---|
| PASSWORD_RESET | `MemberServices.UpdateMemberPassword` | random one-time password, shown ONCE in the confirm response, never stored anywhere |
| SEND_VERIFICATION_EDM | `EDMService.sendTestEmail` | gated on `GURU_VERIFICATION_EDM_TEMPLATE_ID`; fails with an escalate message until set |
| SYNC_PROFILE | Updot forward `PUT /v1/admin/members/sync-profile/{profile_id}` | |
| RESEND_RCI_CONFIRMATION_EDM | `BookingsService.sendRCIUnitEDM(rci_unit_id, {memberRecordID})` | needs rci_unit_id + member_record_id; low-risk resend of the RCI confirmation email |

Every attempt + outcome is audited (`guru_audit_log`: requester, confirmer,
member, before/after, ClickUp id, success) and echoed as a ClickUp comment.

## 4. Ticket lifecycle

- **Open**: first chat message (ticket created before connecting, so the
  agent's greeting arrives first).
- **During**: agent classifies via `update_ticket`; screenshots attach to the
  ClickUp task (`POST /tickets/:ref/attachments`, image/PDF ≤ 8MB; creates
  the task on first attachment if needed).
- **Conversation end** (post-call webhook → `guru-postcall` BullMQ job,
  idempotent per conversation): ClickUp task ensured, redacted transcript
  posted as batched comments, `guru_resolution` data-collection drives
  RESOLVED (auto-resolved tag) / ESCALATED (escalated tag + PM assignee from
  `GURU_CLICKUP_PM_ASSIGNEE`), Viewpoint closed log written.
- **Concierge close** (`POST /tickets/:ref/close`, owner): "no longer an
  issue" — RESOLVED/CLOSED_BY_CONCIERGE, ClickUp comment + task moved to the
  list's closed-type status, Viewpoint log. Connector failures never block
  the local close; they land in audit (`clickup.close_failed`,
  `viewpoint.log_failed`).
- **Auto-close**: hourly sweep closes OPEN tickets inactive 7 days
  (AUTO_CLOSED_INACTIVE) with the same ClickUp/Viewpoint/audit trail.
- **Reopen**: continuing the chat rebinds a new conversation and reopens;
  the agent regains context via `guru_ticket_history`.
- **Viewpoint log status**: written as `CLOSED`, with automatic fallback to
  `OPEN` on a 4xx. Verified against the real API 13 Nov 2026 (GRU-1004):
  CLOSED-on-create works.

## 5. Console UI (`/admin/guru`)

- **Chat** — messenger layout: sidebar (New chat + My cases with status
  dots), full-height conversation. Selecting a case replays its real
  transcripts (fetched from ElevenLabs on demand, redacted, never stored),
  scrolled to the last message; typing reconnects automatically.
  Confirmation cards render inline (Confirm/Cancel, one-time password shown
  once). Header: Close case, End chat, ticket link. Paperclip = screenshot.
- **My tickets** — own cases only; search + status filter; design-system rows.
- **Ticket detail** — summary, proposed actions, ClickUp "Case updates" +
  live team status, Continue this chat, Close case.
- **Admin** (`guru-admin`) — analytics (volume by category, outcomes incl.
  concierge/auto closes, 12-week series, avg time to resolve) + All tickets
  (every concierge, searchable). Super admins additionally manage the
  **edit allowlist** and view the **audit log**.

## 6. RBAC & visibility

| Slug | Grants |
|---|---|
| `guru` | concierge: chat, own tickets, confirm own cards (allowlist still gates writes) |
| `guru-admin` | all tickets, analytics |
| super admin | edit allowlist + audit log (route-guarded `withSuperAdmin`) |

Visibility is enforced by separate guarded routes — "my" handlers scope by
the session user id, never a client-supplied id; non-owned refs return 404.
Role changes require re-login (scopes JWT minted at login; middleware is the
real check). Feature seeds run via migration; assign under Settings → Roles.

## 7. Environment (apps/core/.env)

| Var | Required | What |
|---|---|---|
| `SUBITO_AI_GURU_ELEVENLABS_AGENT_ID` | yes | The Guru agent (separate from Kevo) |
| `GURU_TOOL_SHARED_SECRET` | yes | Random string (32+ chars); uploaded to ElevenLabs by guru-setup as the `X-Guru-Secret` source |
| `GURU_CLICKUP_LIST_ID` | yes for ClickUp | Numeric list id (e.g. `901615999390`), NOT the `6-…-1` view id from the ClickUp URL — the API rejects view ids |
| `GURU_CLICKUP_PM_ASSIGNEE` | optional | Numeric ClickUp user id for escalations (resolve emails via the ClickUp API — emails don't work here) |
| `GURU_PUBLIC_BASE_URL` | optional | Tool URL base; falls back to `KEVO_PUBLIC_BASE_URL` |
| `GURU_VERIFICATION_EDM_TEMPLATE_ID` | optional | Enables SEND_VERIFICATION_EDM |
| `ELEVENLABS_WEBHOOK_SECRET` | yes for post-call | HMAC secret from the dashboard webhook |

Shared with Kevo: `ELEVENLABS_API_KEY`, `CLICKUP_API_TOKEN`,
`CONSOLE_BASE_URL`, `VIEWPOINT_API(_KEY)`, `VIEWPOINT_DATABASE_*`.

## 8. Setup runbook

1. Create the agent in the ElevenLabs dashboard; enable **text-only**
   conversations; paste `docs/subito-ai-guru-system-prompt.md`.
2. Fill the env vars above; then
   `pnpm --filter @karma/core exec tsx src/cmd/guru-setup.ts`
   (idempotent: workspace secret, 9 `guru_*` tools, `guru_resolution`
   data-collection; names are `guru_*` because ElevenLabs matches workspace
   secrets/tools by name — never reuse Kevo's).
3. Workspace **post-call webhook** (dashboard, shared with Kevo):
   `<public base>/v1/kevo/webhooks/post-call`, HMAC; put its secret in
   `ELEVENLABS_WEBHOOK_SECRET`. Core routes events by `agent_id`
   (kevo → kevo queue, guru → guru queue, unknown → acked).
4. Boot core (migrations run on boot; feature seeds `guru`/`guru-admin`),
   assign features to roles, re-login.
5. **Local dev:** ElevenLabs must reach core — tunnel it (e.g.
   `cloudflared tunnel --url http://localhost:9005`). Quick tunnels rotate
   URLs on every restart: update the env base URL, re-run guru-setup (and
   kevo-setup), and fix the dashboard webhook URL each time — or use a named
   tunnel.

## 9. Data model (migration `20261113120000`)

`guru_tickets` (GRU- refs, owner, member_ref, category, status
OPEN/RESOLVED/ESCALATED, resolution AUTO_RESOLVED/ESCALATED/
CLOSED_BY_CONCIERGE/AUTO_CLOSED_INACTIVE, clickup ids, conversation_ids[]),
`guru_pending_actions` (single-use PENDING transitions, race-safe),
`guru_edit_allowlist` (lowercased unique emails), `guru_audit_log`
(best-effort writes, never fail the mutation they describe).
Transcripts are **not stored** — fetched from ElevenLabs on demand, redacted.

## 10. Testing

- `pnpm --filter @karma/core test` — 150 cases across 8 suites
  (`apps/core/src/internal/guru/*.test.ts` + kevo): masking, allowlist
  bypass + identity smuggling, confirmation gate incl. expiry/races,
  injection-as-data, webhook routing/HMAC, ClickUp pipeline, Viewpoint
  CLOSED→OPEN fallback, lifecycle close/sweep. Spec §7 checklist → test
  mapping lives in the stage-7 QA report (all PASS).
- `docs/subito-ai-guru-e2e.md` — 15 executable curl scenarios against the
  running stack (executed: 13 PASS, webhook scenario needs the secret).
- **Live-agent QA replay (13 Nov 2026):** 17 real cases from the ClickUp
  "MemberShip Bugs" list (statuses inprogress / in review) were replayed
  against the running agent over the real ElevenLabs WebSocket (ticket
  created + conversation bound like the console does), each followed by a
  "is there already a ticket / give me the link" probe, plus one reopen test
  on GRU-1004 (ClickUp comment reading). All passed after the fixes below.
  The replay tickets (GRU-1005…1027) remain in the local DB with
  `ticket.postcall_processed` audit markers so neither a webhook delivery
  nor `guru-reprocess.ts` can create ClickUp tasks or Viewpoint logs for
  them. Dev-data caveat: the member DB used for sessions/bookings is sparse
  (sessions for ~25 users), so "no app sessions" answers in dev are data
  artifacts, and its emails are rewritten to `atwi.*` so email lookups fail.

## 11. Known gaps / external dependencies

1. **Admin entitlement lookup API** — partially closed 13 Nov 2026:
   `guru_entitlements` now serves contracts + all-club points lines from the
   Viewpoint API (`clubResortID 0`). Still missing (escalates): product-matrix
   flags (affiliate access, unit restrictions, Subito login allowed), points
   transaction history, fee amounts.
1b. **Tool-build handover (13 Nov 2026)** — built: guru_entitlements (real),
   guru_availability, guru_submission_log, guru_external_booking_status
   (Viewpoint half), RESEND_RCI_CONFIRMATION_EDM action. Parked:
   guru_pms_sync_status (no GuestLine API access — resorts carry gl_* config
   but no client exists; agent escalates). Blocked: guru_email_delivery —
   decision was SendGrid event webhook + 90-day table, but the member
   verification/password emails originate in the OLD system (Updot), whose
   transport this repo cannot confirm; only console emails, EDMService and
   the Guru resend use SendGrid from here. Confirm Updot's sender before
   building. Playbook tool-name alignment (handover §6) still to do.
2. **Knowledge base** — inbox mining, playbooks, review loop (meeting notes
   workstream 1). Tool names for playbook decision trees are final (see §2).
3. **Evaluation set vs past tickets** — ElevenLabs agent-testing, after the
   KB exists.
4. **Cost-per-ticket analytics** — parked per meeting notes §7.
5. **Escalation SLA, ElevenLabs DPA/compliance sign-off** — org decisions.
7. **Tool gaps observed in the 13 Nov 2026 QA run** (17 real ClickUp cases
   replayed against the agent): points **transaction history** (refund/
   forfeiture cases), booking **status-change audit log** (phantom check-in
   case), and **availability/waitlist rules** all forced escalation — the
   entitlement API gap (§11.1) was the single biggest cause of "escalate"
   outcomes. Candidate next tools once vendor APIs exist.
8. **ClickUp search** — the agent cannot search ClickUp (v2 API has no
   free-text task search); duplicate detection covers console-created cases
   only (`existing_cases`). A task filed directly in ClickUp by the tech team
   stays invisible to the agent.
9. Pre-existing, out of scope (reported, needs second reviewer per org IAM
   policy): `POST /v2/admin/console-user-roles/feature` has no role guard;
   `withConsoleUserRole` ignores `is_active`.

## 12. Build history (branch `feature/subito-ai-guru`)

| Commit | Stage |
|---|---|
| 1337e36b | plan |
| 268c171f | 1 — tables, RBAC, skeleton, tickets UI |
| 6aa4d9a4 | 2 — text chat, session minting, webhook agent routing |
| 47fcc334 | 3 — diagnosis tools + guru-setup |
| 73c5f27e | 4 — ClickUp pipeline, reopen context |
| 5650bf7c | 5 — confirmed writes, allowlist gate, Viewpoint closed log |
| 9a81f2e1 | 6 — analytics |
| dc889441 | 7 — hardening QA + system prompt |
| b828dd7f | fix: unordered migrations across merged branches |
| a7599c9a | E2E runbook (executed) |
| 5626cd4b / e7fe84b2 | messenger chat, history replay, UI polish, visibility |
| 5ef7720c / 0ac504d2 | concierge close + 7-day auto-close (+ tests) |
| 172b977c | screenshots → ClickUp, task status sync back |
| e241ac59 | GRU-1004 fixes: existing-case surfacing in lookup/history, webhook 401 logging, prompt honesty (ClickUp timing/scope), `guru-reprocess.ts` |
| 49ce5178 | tool build 1 — guru_entitlements (real; clubResortID 0 verified) |
| 82eccca3 | tool build 2 — guru_availability (inventory + blocking rule) |
| 3af2a42e | tool build 3 — guru_submission_log (booking_requests ↔ Viewpoint) |
| dba13820 | tool build 4 — RESEND_RCI_CONFIRMATION_EDM action |
| cbf50e0c | tool build 5 — guru_external_booking_status (Viewpoint half) |
