toga-ai 1.0.391 → 1.0.392

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: architecture
 status: active
-updated: 2026-07-09
+updated: 2026-07-21
 owners: [jcardinal]
 files:
   - worker2/Controller/Index.php
@@ -53,7 +53,8 @@ All table creation, `ALTER` statements, index changes, and seed data — includi
 `jobType ENUM('ACTION','CRON')`, `cronJobId`, `dtQueued` (NULL = not yet queued),
 `dtStarted` (committed immediately at check-in), `dtCompleted`, `executionTime`,
 `instanceId`, `isSuccess` (NULL pending/running, 0 fail, 1 success), `action`,
-`parameters` JSON, `failureReason`.
+`parameters` JSON, `output` (renamed from `failureReason`; **now holds both** failure text
+**and** successful-run results — see the multi-producer rename note below).
 
 Derived status: `pending` (`dtQueued IS NULL AND isSuccess IS NULL`) → `queued` → `running`
 (`dtStarted` set, `dtCompleted` NULL) → `succeeded`/`failed`.
@@ -61,6 +62,21 @@ Derived status: `pending` (`dtQueued IS NULL AND isSuccess IS NULL`) → `queued
 **`Core.CronJobs`** — `isActive`, `name`, `schedule` (cron expr, **Central tz**),
 `maxExecutionTime` (watchdog seconds, default 300), `action`, `parameters` JSON.
 
+### `WorkerJobs.output` is written by MULTIPLE producers — rename it everywhere at once
+
+The outcome column (renamed from `failureReason` → `output`, MEDIUMTEXT) is written by **four**
+places that must change together: the PHP worker check-out (both paths in `Controller/Index.php`),
+the `Retry()` reset (`Worker/Infrastructure/Worker.php`, which clears `output`), and the Python
+**JobScheduler watchdog** Lambda (`LambdaFunctions/JobScheduler/lambda_function.py`, Part B timeout
+UPDATE). Because this is a **rename, not add-and-keep**, old-code/new-column and new-code/old-column
+both break — so the `dbchanges2` `ALTER TABLE Core.WorkerJobs CHANGE failureReason output MEDIUMTEXT
+NULL` must land **simultaneously** with the code deploy, and the watchdog Lambda must be
+**repackaged/redeployed separately** (a Python zip redeploy, not just a code push) or its UPDATE
+errors on the missing column. The PHP `$failureReason` **local variables** were intentionally left
+unchanged (only the SQL column moved). Do **not** touch the same-named-but-unrelated `failureReason`
+fields on other tables: the `Email` table (`Worker/Infrastructure/Email/Send.php`) and
+`Team.TranscriptExports` (`Worker/Team/Transcripts.php`).
+
 ## The four Lambdas (`worker2/LambdaFunctions/`, Python)
 
 `boto3` is in the runtime; `pymysql`, `croniter`, `pytz` are vendored into the zip.
@@ -91,7 +107,9 @@ New path (`{workerJobId}` present):
 3. Register DB_LOGS / DB_CLIENT_LOGS (try/catch → failure marks job failed, returns 200).
 4. Resolve class+method from action (`Clickup/Webhook` → `_Worker_Clickup::Webhook`).
 5. Call `initialize()` if present, then the action with spread parameters.
-6. **Check-out:** `UPDATE dtCompleted, executionTime, isSuccess, failureReason`. Return 200.
+6. **Check-out:** `UPDATE dtCompleted, executionTime, isSuccess, output`. On success `output` =
+   the composed `"[<requestId>] Successfully Executed (<n>s): <return value>"` string (arrays/objects
+   `json_encode`d, escaped via `_Database::escape()`); on failure `output` = the failure text. Return 200.
 
 Direct-payload path (`action` present, no `workerJobId`): formerly the debug-only "legacy"
 path (untracked, could return HTTP 500). As of 2026-07-07 it is a **first-class tracked
@@ -211,6 +229,11 @@ the MySQL-first design was departed from **on purpose** here.
 
 ## Change history
 
+- 2026-07-21 — `Core.WorkerJobs.failureReason` renamed to `output` and repurposed to capture
+  successful run results as well as failures (success writes the composed "Successfully Executed"
+  message, return value `json_encode`d). Multi-producer rename: PHP worker (both paths), `Retry()`
+  reset, and the JobScheduler watchdog Lambda change together with the `dbchanges2` `CHANGE`
+  migration; watchdog Lambda needs a separate redeploy. (jcardinal)
 - 2026-07-09 — Added the "long-running AI actions — sync vs. async writes" rule: reads-back
   writes go before the AI call, synchronous+committed; post-AI status writes go async.
   Distilled from the Talos Graph-direct pipeline (async pre-AI dedupe writes weren't durable

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-30
+updated: 2026-07-21
 owners: [jcardinal, dfranks, mhammontree]
 files:
   - worker2/Worker/
@@ -133,11 +133,17 @@ Use realistic placeholder values, not empty strings/nulls.
 
 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 +
+- **Returns normally** → `WorkerJobs.isSuccess = 1`, `dtCompleted` set, and the composed success
+  message (`"[<requestId>] Successfully Executed (<n>s): <return value>"`, arrays/objects
+  `json_encode`d) written to the `output` column.
+- **Throws** (any `Throwable`, incl. `Error`) → `isSuccess = 0`, `output` = message +
   `file:line` + full stack trace. (Two earlier phases — DB-logs registration and `initialize()` —
   fail the same way.)
 
+> The outcome column on `Core.WorkerJobs` is named **`output`** (renamed from `failureReason`).
+> It now captures **both** success results and failure text. See
+> [architecture.md](../architecture.md) for the multi-producer rename gotcha.
+
 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.
@@ -169,6 +175,9 @@ be reattempted.
   commit-before-SQS transaction pattern that the worker relies on.
 
 ## Change history
+- 2026-07-21 — `WorkerJobs.failureReason` column renamed to **`output`** and repurposed to store
+  successful execution results as well as failure text; success now writes the composed
+  "Successfully Executed" message (return value `json_encode`d for arrays/objects). (jcardinal)
 - 2026-06-30 — Added the **`DB_CLIENT` auto-registration gotcha**: the dispatcher registers only
   `DB_CLIENT_LOGS`, so a worker loading a `Client_*` model must call
   `_Database::registerClientDatabases($clientId, $environment)` itself (proven by

package/package.json

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