toga-ai 1.0.196 → 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/knowledge/standalone/apps/forward/INDEX.md

@@ -3,6 +3,6 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Forwarder Architecture](architecture.md) | Forwarder is a tiny **standalone PHP application** that powers TOGA's short, branded redirect domains. | forward/forward.ini, forward/index.php, forward/.htaccess, forward/.platform/httpd/conf.d/rewritemap.conf, forward/.ebextensions/rewritemap.config, forward/design/index.php, forward/composer.json |
-| [Design Demo Admin Tool](features/design-demo-admin.md) | A standalone, dependency-free PHP tool served at `https://demo.togatech.com/design` that lets the **design team** publish self-contained "Claude Design" HTML ex | forward/design/index.php, forward/design/.config.example.php, forward/.gitignore, forward/.htaccess, forward/.ebextensions/php-uploads.config |
+| [Design Demo Admin Tool](features/design-demo-admin.md) | A standalone, dependency-free PHP tool served at `https://demo.togatech.com/design` that lets the **design team** publish self-contained "Claude Design" HTML ex | forward/design/index.php, forward/tabs.json, forward/design/.config.example.php, forward/.gitignore, forward/.htaccess, forward/.ebextensions/php-uploads.config |
 | [Encrypted-Link Handler](features/encrypted-link-handler.md) | A `index.php` feature in [Forwarder](../architecture.md) for redirect domains whose URL path carries an **encrypted token** that must be decoded before redirect | forward/index.php |
 | [Static Demo Hosting](features/static-demo-hosting.md) | A lightweight way to host self-contained static HTML pages (demos, exported designs, download landing pages) on the Forwarder app under a clean URL — e.g. | forward/.htaccess, forward/togadesk/index.html |

package/knowledge/standalone/apps/forward/features/design-demo-admin.md

@@ -6,10 +6,11 @@ project: Forwarder
 client: shared
 type: feature
 status: active
-updated: 2026-06-24
+updated: 2026-06-25
 owners: ["jcardinal"]
 files:
   - forward/design/index.php
+  - forward/tabs.json
   - forward/design/.config.example.php
   - forward/.gitignore
   - forward/.htaccess
@@ -94,9 +95,34 @@ auto-deploy ("live in a few minutes").
   brief "Copied ✓" confirmation.
 - **Copy Claude Design prompt** — one-click copy of the standard self-contained-HTML export
   prompt (the same prompt documented in [static-demo-hosting](static-demo-hosting.md)).
+- **Create a tab** (`apiCreateTab`, action `create-tab`) — appends a named tab to
+  `tabs.json`. Case-insensitive dedupe; name length-capped 40. Commits `tabs.json` only.
+- **Move a project to a tab** (`apiSetProjectTab`, action `set-project-tab`) — sets/clears a
+  project's `tab` field; empty string = Unsorted (the field is `unset`). Commits that
+  project's `project.json` **only** — tab membership does not affect the redirect stub, so
+  **no stub rebuild**. `apiCreateProject` also accepts an optional `tab`.
 
 The full action set is: `list`, `create-project`, `upload`, `adopt`, `set-latest`,
-`toggle-version`, `edit-version`, `toggle-project` (plus `bootstrap`).
+`toggle-version`, `edit-version`, `toggle-project`, `create-tab`, `set-project-tab` (plus
+`bootstrap`). `list` also returns the tab list (`{ projects, tabs }`).
+
+### Tab-based organization
+
+Demo projects can be grouped into named **tabs** (e.g. separate Production / Pipeline /
+Sandbox).
+
+- **`tabs.json`** at the repo root holds the ordered tab list — `{"tabs": ["Production",
+  "Pipeline", "Sandbox"]}`. `loadTabs()` returns those three as **defaults when `tabs.json`
+  does not exist yet** (so tabs appear before any are created); the file is only written on
+  the first tab mutation (`create-tab`).
+- Each `project.json` gains an optional **`tab`** field (string). Missing/absent =
+  **"Unsorted"**.
+- **UI:** a filter chip bar (All / each tab / Unsorted / + New tab) with per-tab project
+  counts; clicking a chip filters the list. Each project card has a **Tab `<select>`** to
+  move the project between tabs (on the select's `change`). The New Project modal has a Tab
+  dropdown defaulting to the currently-viewed tab.
+- The **displayed** tab list is the **union** of `tabs.json` order plus any tab names
+  referenced by projects — so removing a tab from `tabs.json` never orphans a project.
 
 ### Naming & validation
 
@@ -117,7 +143,10 @@ anyone who reaches it can publish or unlist. Do not treat the tool as protected.
 
 ## Data model
 
-`project.json` per managed demo (see Versioning model above). No database.
+`project.json` per managed demo (see Versioning model above), plus an optional `tab` string
+field per project (absent = Unsorted). A single repo-root **`tabs.json`** —
+`{"tabs": [...]}` — holds the ordered tab list (defaults to `["Production", "Pipeline",
+"Sandbox"]` until first written). No database.
 
 ## Client variations
 
@@ -158,6 +187,14 @@ None — internal/shared design-team tool.
   `isValidVersionId` + length caps). Added a **Copy URL** button on each project card
   (`navigator.clipboard` → `https://demo.togatech.com/<project>`). Both additive; no new
   security surface. (jcardinal)
+- 2026-06-25 — Added **tab-based organization**: new repo-root `tabs.json` (ordered tab
+  list, defaults Production/Pipeline/Sandbox until first written via `create-tab`), optional
+  `tab` field on `project.json` (absent = Unsorted), and actions **`create-tab`** /
+  **`set-project-tab`** (`apiCreateProject` accepts an optional `tab`). UI filter chip bar
+  with per-tab counts, per-card Tab select, and a Tab dropdown on the New Project modal. The
+  displayed tab list is the union of `tabs.json` and tabs referenced by projects, so dropping
+  a tab from `tabs.json` never orphans a project. `set-project-tab` commits `project.json`
+  only (no stub rebuild). (jcardinal)
 
 ## Related docs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.196",
+  "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",