toga-ai 1.0.144 → 1.0.145

package/knowledge/2.0/apps/worker2/features/creating-worker-actions.md

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-08
-owners: [jcardinal]
+updated: 2026-06-18
+owners: [jcardinal, dfranks]
 files:
   - worker2/Worker/
   - worker2/Controller/Index.php
@@ -126,6 +126,31 @@ curl -X POST https://worker.togahub.com/ \
 
 Use realistic placeholder values, not empty strings/nulls.
 
+## How exceptions & retries work
+
+The EB worker dispatcher (`Controller/Index.php::worker()`) wraps your action call in
+`try { } catch (\Throwable $e)`:
+- **Returns normally** → `WorkerJobs.isSuccess = 1`, `dtCompleted` set.
+- **Throws** (any `Throwable`, incl. `Error`) → `isSuccess = 0`, `failureReason` = message +
+  `file:line` + full stack trace. (Two earlier phases — DB-logs registration and `initialize()` —
+  fail the same way.)
+
+Crucially, the worker **always returns HTTP 200, even on a throw**, so SQS deletes the message
+immediately. **There is no DLQ and no automatic retry.** A throw makes the failure *visible* (a
+failed `WorkerJobs` row to alert on) — it does **not** re-run the job.
+
+So **do not design "throw so it retries" — it won't.** To actually retry / self-heal:
+- **Re-enqueue** with `_Worker::runTask('Category/Action/Method', [...])` — inserts a fresh
+  `WorkerJobs` row + SQS message, so it genuinely re-runs. Carry your own **attempt counter** in the
+  parameters to bound it.
+- Or **in-process retry** *within* the method (it's a background worker with a 3600s visibility
+  budget — a bounded sleep+retry loop is fine here, unlike a request handler).
+- Or **manual** `_Worker_Infrastructure_Worker::Retry($id)` / the reset-fields SQL, or a periodic
+  reconcile cron as a backstop.
+
+Rule of thumb: `throw` to surface a genuine failure; `runTask`/in-process loop when the work should
+be reattempted.
+
 ## Gotchas
 
 - Class must be **`abstract`** and methods **`public static`** or routing fails.
@@ -135,4 +160,8 @@ Use realistic placeholder values, not empty strings/nulls.
   commit-before-SQS transaction pattern that the worker relies on.
 
 ## Change history
+- 2026-06-18 — Documented worker-action **exception/retry semantics**: dispatcher catches `Throwable` →
+  `isSuccess=0`+`failureReason`, **always HTTP 200, no DLQ, no auto-retry**; throwing surfaces a failure
+  but does not re-run — retry via `_Worker::runTask` re-enqueue (attempt-counter), in-process loop, or
+  manual `Retry()`. (dfranks)
 - 2026-06-08 — Documented the worker-action contract (path→class/method convention, parameter typing, webhook/cron templates); replaces the former `/worker2-action` skill. (jcardinal)

package/knowledge/2.0/apps/worker2/features/netsuite-opportunity-sync.md

@@ -147,6 +147,17 @@ Shared helpers: `buildCustomFields()` (the field array, used by both create and
   it on the payload; the new contract drops it).
 - Every ClickUp `_ApiRequest` calls `setLogging(self::CLICKUP_API_LOGGING_ENABLED=false)`, so ClickUp
   traffic is not written to the Logs DB.
+- **Two `_Component_Api_Netsuite` classes exist — edit the right one.** worker2 calls the **global**
+  `_Component_Api_Netsuite`, autoloaded from `_underscore/Component/Api/Netsuite/Netsuite.php`; `api2`
+  ships a *separate* `namespace api` copy (`\api\_Component_Api_Netsuite`) for its own use. Editing the
+  api2 copy has **no effect** on the worker2 webhook integration — change the `_underscore` one.
+- **NetSuite REST calls are NOT logged to `Logs.Api`.** `_Component_Api_Netsuite::send()` calls
+  `setLogging(false)`, so unlike platform traffic and ClickUp/Freshservice/Sentry (which land in the
+  logs-cluster `Logs.Api` with full request + `responsePayload`), NetSuite request/response bodies are
+  not captured — you can't pull a historical NetSuite response for debugging. That cost us the response
+  bodies when diagnosing the [open-orders read-after-write lag](./netsuite-salesorder-open-orders-sync.md);
+  removing that `setLogging(false)` is under review (handle the 20–50 KB payload volume the
+  prod-appropriate way — retention/sampling/summary — not by defaulting logging off).
 
 ## Data model
 
@@ -306,6 +317,11 @@ same **skip-if-unchanged** compare on the extracted values, and **actor-identity
 trigger a CU→NS write. The NS→CU change-detection above is the complementary backstop, not a substitute.
 
 ## Change history
+- 2026-06-18 — Documented two NetSuite-client gotchas: **two `_Component_Api_Netsuite` copies** (worker2
+  uses the global `_underscore` one; api2 has a separate `namespace api` copy — edit the right one), and
+  `send()`'s `setLogging(false)` means **NetSuite calls aren't logged to `Logs.Api`** (no historical
+  response bodies; removal under review). Also dropped the debunked dev-laptop rationale from the
+  ClickUp-logging note. (dfranks)
 - 2026-06-18 — **Diagnosed the live opportunity-import gap as a deployment misconfig + characterized the
   AMQ burst behavior.** The Opportunity `ue_amq_enqueue` deployment was `Released` but with an **empty
   audience** (~4:41–5:39 pm) so it enqueued nothing; missing opps had no queue row and no worker2 job

package/package.json

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