toga-ai 1.0.545 → 1.0.546

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

@@ -30,6 +30,7 @@
 | [Background Email-Template Worker (_Worker_Notification_EmailTemplate)](features/notification-email-template.md) | `_Worker_Notification_EmailTemplate::Send(...)` dispatches a **stored, client-defined `EmailTemplates` row off-thread** as a background WorkerJob. | worker2/Worker/Notification/EmailTemplate.php, worker2/Worker/Client/True.php, _underscore/Model/Client/EmailTemplate.php |
 | [DB-Driven Notification (Internal) Email](features/notification-email.md) | Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated, not client-facing transactional mail) are sent through one worker | worker2/Worker/Notification/Email.php, _underscore/Model/Client/EmailTemplate.php, dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql, dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.sql |
 | [NYCHH Asset-Tag Backfill (worker2)](features/nychh-asset-tag-backfill.md) | Keeps NYC Health & Hospitals (`Client_Nychh`) unit asset tags and MAC addresses synced from NetSuite. | worker2/Worker/Client/Nychh.php, worker2/Worker/Client/Nychh/AssetTagBackfill.php, worker/crons/toga2/netsuite/verify_fulfillment_asset_tag_sync_nychh.php, worker/crons/toga2/netsuite/backfill_all_asset_tags_from_netsuite_nychh.php |
+| [OneUptime Incident → ClickUp Task Sync (Monitor/Oneuptime/SyncIncidents)](features/oneuptime-incident-clickup-sync.md) | An internal/shared TOGA ops feature: worker2 polls the OneUptime API every 15 minutes for **currently-open** incidents and ensures a ClickUp task exists for eac | worker2/Component/Api/Oneuptime/Oneuptime.php, worker2/Worker/Monitor/Oneuptime.php, worker2/Config/production.ini, dbchanges2/Team/2026-08-10a - OneUptime Incident ClickUp Tasks.sql, dbchanges2/Core/2026-08-10b - OneUptime Incident Sync CronJob.sql |
 | [OneUptime push-metric monitors for 2.0 workers](features/oneuptime-worker2-monitoring.md) | A second, **OneUptime-reporting** monitoring pattern for the 2.0 worker2 tier, ported from the 1.0 `App_SystemMonitor_Compass` monitors. | worker2/Worker/Monitor/Compass.php, worker2/Worker/Client/Compass.php, worker2/composer.json, _underscore/Cloud.php, worker2/Worker/Monitor/Operations.php |
 | [Platform Cache Cleanup (_Worker_Platform_Cache — Clean + Truncate)](features/platform-cache-cleanup.md) | `_Worker_Platform_Cache` owns maintenance of the shared **Cache** cluster that backs api2's [multi-client data retrieval](../../api2/features/cross-client-data- | worker2/Worker/Platform/Cache.php, worker2/Controller/Index.php, worker2/_.php, dbchanges2/Core/2026-07-27a - PlatformCacheCleanCron.sql |
 | [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 |

package/knowledge/2.0/apps/worker2/features/oneuptime-incident-clickup-sync.md

@@ -0,0 +1,121 @@
+---
+title: OneUptime Incident → ClickUp Task Sync (Monitor/Oneuptime/SyncIncidents)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-08-10
+owners: ["jcardinal"]
+files:
+  - worker2/Component/Api/Oneuptime/Oneuptime.php
+  - worker2/Worker/Monitor/Oneuptime.php
+  - worker2/Config/production.ini
+  - dbchanges2/Team/2026-08-10a - OneUptime Incident ClickUp Tasks.sql
+  - dbchanges2/Core/2026-08-10b - OneUptime Incident Sync CronJob.sql
+related:
+  - ./oneuptime-worker2-monitoring.md
+  - ./error-escalation-cron.md
+  - ./creating-worker-actions.md
+  - ./team-sprint-management.md
+---
+
+## Summary
+
+An internal/shared TOGA ops feature: worker2 polls the OneUptime API every 15 minutes for
+**currently-open** incidents and ensures a ClickUp task exists for each, so operational
+incidents become actionable tickets automatically without duplicates. This is the **first
+*reader* of the OneUptime API** in worker2 — until now OneUptime was **push-only** (workers
+POST metrics/heartbeats to Incoming-Request monitors; see
+[OneUptime push-metric monitors](./oneuptime-worker2-monitoring.md)). The model was "dumb
+reporter, smart monitor"; this feature adds the reader half.
+
+## Key files / entry points
+
+- `worker2/Component/Api/Oneuptime/Oneuptime.php` — `_Component_Api_Oneuptime`, the OneUptime
+  API read client, modeled on `_Component_Api_Togaiq`. Reads a new `[oneuptime]` config group
+  (endpoint, api_key, project_id) via `_Config`; `isConfigured()` guard; `send()` wraps
+  `_ApiRequest` with `APIKey` + `ProjectID` headers; `getActiveIncidents()` returns normalized
+  open incidents (filters out resolved **in PHP**).
+- `worker2/Worker/Monitor/Oneuptime.php` — `_Worker_Monitor_Oneuptime::SyncIncidents(): string`,
+  the cron action. Returns a structured summary string on every path
+  (`incidentsPolled` / `created` / `skipped` / `failed`).
+
+## How it works
+
+Canonical worker2 scheduled-3rd-party-API-job shape (see
+[Creating Worker Actions](./creating-worker-actions.md)): a `Core.CronJobs` row (cron expr,
+Central tz) → CronScheduler Lambda enqueues → `Controller/Index::worker()` dispatches the
+`action` `Monitor/Oneuptime/SyncIncidents` to `_Worker_Monitor_Oneuptime::SyncIncidents`.
+HTTP goes through `_ApiRequest`; secrets come from `_Config::oneuptime()` reading
+`Config/<env>.ini`; ClickUp uses `_Component_Api_Clickup::send()`.
+
+### Open-only
+
+Only currently-open incidents are synced. The list route returns all incidents and resolved
+ones are filtered out in PHP inside `getActiveIncidents()`.
+
+### Claim-first (unique-key) dedup
+
+For each open incident, INSERT a ledger row into `OneUptimeIncidentTasks` keyed on the
+OneUptime incident id **before** calling ClickUp. A unique-key violation means a task already
+exists → skip. On success, create the ClickUp task via
+`_Component_Api_Clickup::send('POST','/list/{listId}/task', …)` and attach the returned id to
+the ledger row; on failure, **delete the claim and re-throw**. This is the established
+worker2 way to prevent duplicate ClickUp tasks under overlapping cron runs — pattern copied
+from `_Worker_Infrastructure_Errors::createClickupTask`. `INSERT … WHERE NOT EXISTS` is
+**insufficient** under REPEATABLE READ; the UNIQUE key is the concurrency arbiter.
+
+### Target list = current sprint list
+
+The ClickUp task lands in the **current sprint** list, resolved by `GET /folder/{id}` and
+matching the list whose `start_date`/`due_date` window contains now (mirrors
+`_Worker_Team_Sprint::SprintLock` — see [Team Sprint Management](./team-sprint-management.md)
+and the sprint-promotion note in [Error Escalation Cron](./error-escalation-cron.md)). Folder
+id is read from `[clickup] sprint_folder_id` with a constant fallback (`90020432579`).
+
+## Data model
+
+`OneUptimeIncidentTasks` (CREATE on the **Team** cluster — chosen over Logs;
+`dbchanges2/Team/2026-08-10a`): `id`, `uuid char(36)`, `dtCreated`,
+`oneuptimeIncidentId varchar(64)`, `clickupIdentifier varchar(64) NULL`. The **UNIQUE KEY on
+`oneuptimeIncidentId`** is the dedup contract, same rationale as `IssueClickupTasks`.
+
+## Provisioning / deploy
+
+- `dbchanges2/Core/2026-08-10b` inserts the `Core.CronJobs` row: action
+  `Monitor/Oneuptime/SyncIncidents`, schedule `*/15 * * * *`, `maxExecutionTime` 120, seeded
+  **`isActive = 0`**. Flip to 1 only after (a) the ledger table exists, (b) the `[oneuptime]`
+  config group is populated, and (c) the incident-list route is confirmed.
+- `[oneuptime]` config group (endpoint, api_key, project_id) added to
+  `worker2/Config/production.ini` with placeholders — **values are filled by the developer,
+  not committed**. Credentials live only in the ini files.
+
+## Configuration / credentials
+
+- `[oneuptime]` — `endpoint`, `api_key`, `project_id`. The hosted OneUptime SaaS base is
+  `https://oneuptime.com` (confirmed from `worker/.ebextensions/045_oneuptime_agent.config`);
+  the REST API path is appended to that base.
+- `[clickup]` — `sprint_folder_id` (fallback constant `90020432579`) plus the ClickUp token.
+  ClickUp/OneUptime token **values** live in `worker2/Config/<env>.ini` — location only,
+  never the value.
+
+## Gotchas / known issues
+
+- **Incident-list route/fields are PLACEHOLDER** (`/api/incident/get-list`) pending
+  confirmation against the live OneUptime instance. Do not enable the cron (`isActive = 1`)
+  until the route and returned fields are verified.
+- **OneUptime cannot filter open-only server-side here** — resolution filtering happens in
+  PHP, so the returned field set must actually carry the resolved/open state.
+- Ship the worker2 code deploy and both dbchanges2 migrations **together**; the cron row is
+  inert until the action is deployed and the ledger table exists.
+
+## Change history
+- 2026-08-10 — Built: first OneUptime API *reader* (`_Component_Api_Oneuptime`) + the
+  `Monitor/Oneuptime/SyncIncidents` cron that claim-first-dedups an open incident into a
+  ClickUp task in the current sprint list; new `OneUptimeIncidentTasks` ledger (Team cluster,
+  UNIQUE on incident id) and a seeded-inactive `*/15 * * * *` cron row. Incident-list route
+  left PLACEHOLDER pending confirmation. (jcardinal)
+</content>
+</invoke>

package/knowledge/2.0/apps/worker2/features/oneuptime-worker2-monitoring.md

@@ -15,6 +15,7 @@ files:
   - _underscore/Cloud.php
   - worker2/Worker/Monitor/Operations.php
 related:
+  - ./oneuptime-incident-clickup-sync.md
   - ./monitoring-framework.md
   - ./all-client-email-queue-monitor.md
   - ../../_underscore/features/cloud-s3-helpers.md
@@ -211,6 +212,10 @@ check for another client.
   monitors must pass the region (see [Cloud S3 helpers](../../_underscore/features/cloud-s3-helpers.md)).
 
 ## Change history
+- 2026-08-10 — Noted that worker2 gained its **first OneUptime API *reader*** (this doc covers
+  the push-only half; OneUptime was previously push-only, "dumb reporter, smart monitor"). The
+  reader polls open incidents and files ClickUp tasks — see
+  [OneUptime Incident → ClickUp Task Sync](./oneuptime-incident-clickup-sync.md). (jcardinal)
 - 2026-08-10 — Documented OneUptime incident/alert `{{requestBody.*}}` templating (missing
   paths → empty string; `Not Recieved In Minutes` heartbeat spelling), discovered while
   wiring the second all-client `_Worker_Monitor_Operations` monitor —

package/knowledge/INDEX.md

@@ -18,8 +18,8 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 48 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 43 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 49 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **worker2** (Worker) — 44 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 22 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 8 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 5 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.545",
+  "version": "1.0.546",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",