toga-ai 1.0.197 → 1.0.198

package/knowledge/2.0/apps/ai-bdr/features/call-orchestration.md

@@ -17,6 +17,7 @@ files:
 related:
   - ../architecture.md
   - vapi-integration.md
+  - ../../worker2/features/vapi-webhook-handler.md
 ---
 
 ## Summary
@@ -204,8 +205,23 @@ gracefully handles `"Information not available"`.
 
 ## Where the PHP code lives
 
-**Not in this repo.** The handler lives in the TOGA worker repo (`worker`
-for 1.0 or `worker2` for 2.0). Likely class shape:
+**Now committed in `worker2`** as `_Worker_Vapi` (`worker2/Worker/Vapi.php`,
+the webhook) alongside the outbound dialer `_Worker_Ai_Bdr_Vapi`
+(`worker2/Worker/Ai/Bdr/Vapi.php`). Full detail:
+**`2.0/apps/worker2/features/vapi-webhook-handler.md`**.
+
+> **Corrections confirmed against the live `_Worker_Vapi` code (2026-06-24):**
+> 1. **Structured output is in `artifact.structuredOutputs`** (keyed by a random
+>    UUID; first entry's `result`), **not** `analysis.structuredData` —
+>    `analysis{}` is always empty in practice.
+> 2. **The webhook join key is `assistantOverrides.metadata.contactAttemptUuid`**
+>    (the dialer pre-creates the `ContactAttempt` and passes its UUID). `call.id`
+>    is stored only as `c_vapiCallIdentifier`, not used as the join key.
+> 3. **Filter on `message.type`** — only `end-of-call-report` is processed;
+>    `status-update`/`hang`/etc. are acknowledged and skipped. Inbound and test
+>    calls carry no `contactAttemptUuid` and must be skipped gracefully.
+
+Historical (pre-commit) shape guess:
 
 - 1.0: an `App_Controller_*` for the webhook (under the framework's HTTP
   surface), with an `App_Worker_*` or scheduled cron for cadence.

package/knowledge/2.0/apps/worker2/INDEX.md

@@ -15,4 +15,5 @@
 | [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. | worker2/Worker/Startech.php |
 | [Team Sprint Management & Reporting](features/team-sprint-management.md) | `_Worker_Team_Sprint` (file `Worker/Team/Sprint.php`) is the engine behind TOGA's internal **development-sprint process and reporting**. | worker2/Worker/Team/Sprint.php |
 | [Teams Meeting Transcript Export](features/teams-transcript-export.md) | `_Worker_Team_Transcripts` (action `Team/Transcripts/Export`) polls Microsoft Graph for Teams meeting transcripts produced by a set of organizers, classifies ea | worker2/Worker/Team/Transcripts.php, worker2/Config/production.ini, worker2/Database/TeamsTranscriptExports.sql, dbchanges2/Core/2026-06-18a - Teams Transcript Export schedule.sql |
+| [VAPI Webhook Handler (worker2 — AI-BDR end-of-call processing)](features/vapi-webhook-handler.md) | `_Worker_Vapi` ([worker2/Worker/Vapi.php](worker2/Worker/Vapi.php)) is the **PHP side of the AI-BDR call loop** — the webhook that receives VAPI's end-of-call r | worker2/Worker/Vapi.php, worker2/Worker/Ai/Bdr/Vapi.php |
 | [WJE Freshservice Sync (worker2)](features/wje-freshservice-sync.md) | WJE ("WJE IT", helpdesk `wje.freshservice.com`) is a **Freshservice**-based help-desk client whose tickets, contacts, assets, groups, categories, and canned res | worker2/Worker/Wje.php, _underscore/Component/Api/Wje/Wje.php, _underscore/Model/Wje/Ticket.php, _underscore/Model/Wje/TicketNote.php, _underscore/Model/Wje/Contact.php, _underscore/Model/Wje/Unit.php, _underscore/Model/Wje/TicketTeam.php, _underscore/Model/Wje/TicketCategory.php, _underscore/Model/Wje/AssetType.php, _underscore/Model/Wje/PredefinedReply.php, library/app/api/wje.php, worker/crons/toga2/wje/import_supporting_records.php, worker/crons/toga2/wje/sync_togasupply_wje.php, worker/crons/notifications/reports/wje/wje_common.php, library/app/systemmonitor/wje.php, dbchanges2/Client_Wje/2024-10-04 - WjeOnboarding.sql |

package/knowledge/2.0/apps/worker2/features/vapi-webhook-handler.md

@@ -0,0 +1,156 @@
+---
+title: VAPI Webhook Handler (worker2 — AI-BDR end-of-call processing)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-24
+owners: [snaredla]
+files:
+  - worker2/Worker/Vapi.php
+  - worker2/Worker/Ai/Bdr/Vapi.php
+related:
+  - ../../ai-bdr/features/call-orchestration.md
+  - ../../ai-bdr/features/vapi-integration.md
+---
+
+## Summary
+
+`_Worker_Vapi` ([worker2/Worker/Vapi.php](worker2/Worker/Vapi.php)) is the **PHP side of the
+AI-BDR call loop** — the webhook that receives VAPI's end-of-call report, writes the call
+results back onto the originating `ContactAttempt`, and dispatches the post-call action
+(book meeting / schedule callback / nurture / DNC). This is the concrete handler that the
+`ai-bdr` repo's `call-orchestration.md` referred to as "lives in worker/worker2 — add a
+doc when committed."
+
+It is the **counterpart** to the outbound dialer `_Worker_Ai_Bdr_Vapi`
+([worker2/Worker/Ai/Bdr/Vapi.php](worker2/Worker/Ai/Bdr/Vapi.php)), which places the calls.
+
+## Key files / entry points
+
+| File | Role |
+|---|---|
+| `worker2/Worker/Vapi.php` (`_Worker_Vapi`) | Inbound **webhook** — processes `end-of-call-report`, writes back, dispatches actions |
+| `worker2/Worker/Ai/Bdr/Vapi.php` (`_Worker_Ai_Bdr_Vapi`) | Outbound **dialer** — creates the `ContactAttempt`, places the VAPI call |
+
+- Action route: `Vapi/Webhook` → `webhook.togahub.com/vapi` (VAPI server messages POST here).
+- `initialize()` registers the `Client_True` DB connection (`_underscore::DB_CLIENT`).
+
+## How it works
+
+1. **`Webhook($payload, $headers)`** — JSON-decodes the body, takes `message`, hands off to
+   `processVapiEndOfCallPayload()`.
+2. **`processVapiEndOfCallPayload()`**:
+   - Reads `call.assistantOverrides.metadata.contactAttemptUuid` (falls back to
+     `call.metadata`).
+   - Loads `_Model_True_ContactAttempt` by that UUID. This is the **join key** back to our DB.
+   - Extracts structured output via `extractVapiStructuredOutput()`.
+   - `updateContactAttempt()` writes the results, then `executePostCallActions()` dispatches.
+3. **`extractVapiStructuredOutput($artifact)`** — returns the first
+   `artifact.structuredOutputs[*].result` array. **`analysis{}` is always empty — the data
+   lives in `artifact.structuredOutputs`, keyed by a random UUID.**
+4. **`updateContactAttempt()`** — maps `structured.phpWorkerAction` → `c_callOutcome` /
+   `c_actionToTake` via `$actionMap`; builds a payload of only non-empty `c_*` fields (so
+   blanks never overwrite existing data); converts VAPI ISO timestamps to **Central Time**;
+   persists via `_Component_Api_Toga::send('PUT', '/contact-attempts/{uuid}', …)` (Toga 2.0
+   REST API, **not** a direct DB write); also clears the contact's `dtNextContactRequested`.
+5. **`executePostCallActions()`** — `switch ($contactAttempt->c_actionToTake)`:
+   - `BOOK_CALCOM_MEETING` → `actionCalComBookMeeting` (Cal.com booking + queue
+     `Ai/Bdr/Netsuite/createLeadFromBookedMeeting` + mark COMPLETED)
+   - `SCHEDULE_CALLBACK` → `actionScheduleCallback` (sets `dtNextContactRequested` +
+     `contactCallTypeId=CALLBACK`)
+   - `SEND_NURTURE_EMAIL` → `actionSendNurtureEmail` (queue
+     `Ai/Bdr/Netsuite/createLeadFromNurtureEmail` + mark COMPLETED)
+   - `DO_NOT_CALL` → `actionFlagDnc` (`isOkayToCall=0` + EXCLUDE from PENDING/ACTIVE campaigns)
+   - `NO_ACTION` / default → reset the campaign-contact to PENDING
+
+### phpWorkerAction → outcome/action map
+
+| `phpWorkerAction` | `c_callOutcome` | `c_actionToTake` |
+|---|---|---|
+| `BOOK_CALCOM_MEETING` | MEETING_BOOKED | BOOK_CALCOM_MEETING |
+| `SCHEDULE_CALLBACK` | CALLBACK_SCHEDULED | SCHEDULE_CALLBACK |
+| `SEND_NURTURE_EMAIL` | NURTURE_REQUESTED | SEND_NURTURE_EMAIL |
+| `FLAG_DNC_REMOVE_FROM_CAMPAIGNS` | DNC_REQUESTED | DO_NOT_CALL |
+| `MARK_NOT_INTERESTED` | NOT_INTERESTED | DO_NOT_CALL |
+| `MARK_WRONG_PERSON` | WRONG_PERSON | DO_NOT_CALL |
+| `MARK_VOICEMAIL_RETRY` | VOICEMAIL | NO_ACTION |
+| `MARK_NO_ANSWER_RETRY` | NO_ANSWER | NO_ACTION |
+| `MARK_GATEKEEPER_BLOCKED_RETRY` | GATEKEEPER_BLOCKED | NO_ACTION |
+
+## The contactAttemptUuid write-back mechanism
+
+`contactAttemptUuid` is the **sole linkage** between a VAPI call and our DB:
+
+1. The dialer (`_Worker_Ai_Bdr_Vapi`) creates the `ContactAttempt` row **before** placing the
+   call ([Ai/Bdr/Vapi.php:438](worker2/Worker/Ai/Bdr/Vapi.php#L438),
+   [:694](worker2/Worker/Ai/Bdr/Vapi.php#L694)) and passes its UUID in
+   `assistantOverrides.metadata.contactAttemptUuid`
+   ([Ai/Bdr/Vapi.php:628](worker2/Worker/Ai/Bdr/Vapi.php#L628)).
+2. VAPI echoes that same metadata onto **every** server event for the call.
+3. The webhook loads the row by that UUID and writes results back to it.
+
+`contactId` and `campaignId` are read from the **loaded `ContactAttempt` row**, never from the
+webhook payload. `call.id` is stored only as `c_vapiCallIdentifier`.
+
+## Message-type filtering (the bug this doc was born from)
+
+VAPI sends the webhook **many** server-message types: `status-update`, `hang`,
+`speech-update`, `end-of-call-report`, etc. **Only `end-of-call-report` carries the call data
+(`artifact` / structured output) and should be processed.** The handler must guard on
+`message.type === 'end-of-call-report'` in `Webhook()` and acknowledge (`return 'ok'`) all
+other types before they reach `processVapiEndOfCallPayload()`.
+
+- **Regression origin:** commit `583f6be` "Added remaining webhooks" (2026-05-14) created this
+  file and broadened the VAPI subscription to all server-message types. Without a type guard,
+  every event was processed as an end-of-call report. First Sentry errors appeared ~late May.
+- **Symptom:** `Warning: Undefined property: stdClass::$contactAttemptUuid` (promoted to an
+  `ErrorException` by the framework error handler, captured by Sentry).
+
+## Inbound / test calls vs worker-placed outbound calls
+
+The metadata shape depends on **who placed the call**, not the event type:
+
+- **Outbound (our dialer)** → metadata carries `contactAttemptUuid` (every event type,
+  including status-updates).
+- **Inbound calls and dashboard test calls** → **no `contactAttemptUuid`** (they never went
+  through our dialer, so no `ContactAttempt` was pre-created). Test calls may instead carry
+  hand-typed metadata like `{contactId, campaignId, attemptNumber}`.
+
+Therefore an `end-of-call-report` can legitimately arrive **without** a `contactAttemptUuid`
+(inbound/test). Those have no attempt to write back to and should be **skipped gracefully**
+(`return 'ok'`), not thrown — otherwise they raise `Contact Attempt not found` and fail the
+job. `Contact Attempt not found` should be reserved for a report that *has* a
+`contactAttemptUuid` but no matching row (a real data-integrity anomaly).
+
+## Data model
+
+Writes to `ContactAttempts` (via Toga 2.0 API) — `dtStarted`, `dtEnded`, `transcript`,
+`contactCallTypeId`, and many `c_*` fields (`c_callOutcome`, `c_actionToTake`,
+`c_prospectSentiment`, `c_qualificationScore`, `c_callSummary`, `c_meetingTime`,
+`c_meetingType`, `c_contactEmail`, `c_callbackTime`, `c_recordingUrl`, `c_callCost`,
+`c_vapiCallIdentifier`, `c_dncRequested`, etc.). Also updates `Contacts`
+(`dtNextContactRequested`, `contactCallTypeId`, `isOkayToCall`) and `Campaigns_Contacts`
+status. See the `ai-bdr` skill / `_Model_True_ContactAttempt` for the full field list.
+
+## Gotchas / known issues
+
+- **Structured data is in `artifact.structuredOutputs`, not `analysis.structuredData`.**
+  `analysis{}` is always empty. (Corrects the older `ai-bdr/call-orchestration.md`.)
+- **Join key is `contactAttemptUuid`, not `call.id`.** `call.id` is only stored as
+  `c_vapiCallIdentifier`.
+- **No message-type guard = errors.** Always filter to `end-of-call-report` first.
+- **Persistence is via the Toga REST API**, not a direct model `save()` — failures are
+  caught and logged, not re-thrown.
+- **Timestamps are stored in Central Time**; Cal.com booking converts `c_meetingTime` back to
+  UTC.
+
+## Related docs
+- [AI-BDR Call Orchestration (the PHP↔VAPI contract)](../../ai-bdr/features/call-orchestration.md)
+- [VAPI Integration — assistants, tools, structured output](../../ai-bdr/features/vapi-integration.md)
+
+## Change history
+- 2026-06-24 — Initial doc: webhook handler, contactAttemptUuid write-back, message-type
+  filtering bug, inbound/test vs outbound metadata. (snaredla)

package/knowledge/INDEX.md

@@ -16,7 +16,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 14 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 14 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 15 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 6 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 2 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.197",
+  "version": "1.0.198",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",