toga-ai 1.0.550 → 1.0.552

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

@@ -226,6 +226,16 @@ metrics**, not the database.
 ## Gotchas
 
 - Class must be **`abstract`** and methods **`public static`** or routing fails.
+- **A JSON-object parameter arrives as `stdClass`, not `array` — type it `object|array` and
+  cast.** The dispatcher decodes `Core.CronJobs.parameters` and casts **only the top level** to
+  an array (`$parameters = (array) $message->parameters;` in `Controller/Index.php`, ~L455/692),
+  then spreads it as named args. So a **nested JSON object** value stays a PHP `stdClass`; a
+  method that declares that parameter as strict `array` throws a `TypeError`
+  (*"must be of type array, stdClass given"*) at dispatch. Declare such a parameter as
+  `object|array` and `(array)`-cast it at the top of the method. (Nested JSON **arrays** decode
+  to PHP arrays fine — only JSON **objects** become `stdClass`.) This bit
+  `_Worker_Infrastructure_CloudWatch::ElasticBeanstalkHealth`'s `environments` region-map in
+  production — see [cross-account-aws-access.md](./cross-account-aws-access.md).
 - Webhook headers are **lowercased** by API Gateway (`X-GitHub-Event` → `x-github-event`).
 - If the action needs a client DB, register it in `initialize()` — it runs before the method.
 - **Worker actions do NOT auto-register `DB_CLIENT`.** The dispatcher registers only
@@ -259,6 +269,12 @@ metrics**, not the database.
   commit-before-SQS transaction pattern that the worker relies on.
 
 ## Change history
+- 2026-08-11 — Added the **nested-JSON-object → `stdClass` dispatch gotcha**: the dispatcher casts
+  only the top level of `CronJobs.parameters` to an array before spreading as named args
+  (`Controller/Index.php` ~L455/692), so a nested JSON object stays `stdClass` and a strict
+  `array` param throws a `TypeError` at dispatch — type such params `object|array` and
+  `(array)`-cast. Surfaced fixing `ElasticBeanstalkHealth`'s `environments` region-map in
+  production. (jcardinal)
 - 2026-08-10 — Documented that **`debug_mode` changes `runTask`'s dispatch** (1 = synchronous
   `_ApiRequest` POST to `_Config::api('worker')`, running the action inside the caller's open
   transaction so any read-back fails; 0 = SQS enqueue), plus the debug-mode side effects

package/knowledge/2.0/apps/worker2/features/cross-account-aws-access.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-10
+updated: 2026-08-11
 owners: [jcardinal]
 files:
   - worker2/Component/Aws/Workloads/Workloads.php
@@ -88,20 +88,49 @@ it**.
 
 ## First consumer — ElasticBeanstalkHealth (worked example)
 
-`_Worker_Infrastructure_CloudWatch::ElasticBeanstalkHealth(awsAccountId,
-elasticBeanstalkEnvironmentNames, oneuptimeUrl, region)` is a **parameterized cron** (args
-spread from `Core.CronJobs.parameters` as named args) that reads each EB environment's
-overall health through `_Component_Aws_Workloads::client(...)`, maps `HealthStatus`
-`Degraded`/`Severe` → `alarm:"HIGH"`, and pushes a **non-fatal** OneUptime heartbeat
-(`setLogging(false)`, `setThrowExceptionsOnFailure(false)` — the Compass push pattern; see
+`_Worker_Infrastructure_CloudWatch::ElasticBeanstalkHealth(string $awsAccountId,
+array $environments, string $oneuptimeUrl)` is a **parameterized cron** (args spread from
+`Core.CronJobs.parameters` as named args) that reads each EB environment's overall health
+through `_Component_Aws_Workloads`, maps `HealthStatus` `Degraded`/`Severe` →
+`alarm:"HIGH"`, and pushes a **non-fatal** OneUptime heartbeat (`setLogging(false)`,
+`setThrowExceptionsOnFailure(false)` — the Compass push pattern; see
 [OneUptime worker2 monitoring](./oneuptime-worker2-monitoring.md)).
 
-It was refactored this session to use the new helper: the prior inline STS/credential code
-and the `HEALTH_ASSUME_ROLE_NAME` / `HEALTH_ASSUME_ROLE_SESSION` constants were removed in
-favor of `_Component_Aws_Workloads` + the `[cloud]` config keys. The prior
-`CheckBeanstalks()` action was renamed `ElasticBeanstalkInstances()`
-(dbchanges2 `Core/2026-08-10c` updates the CronJobs action name; `Core/2026-08-10d` seeds
-the new parameterized `ElasticBeanstalkHealth` cron row, `isActive=0`).
+**One monitor spans multiple regions in one account.** `$environments` is a **map of
+region → environment names** (each value an array or a comma-separated string), so a single
+monitor can watch EB environments across different regions of the same AWS account. The old
+flat `elasticBeanstalkEnvironmentNames` list plus a single scalar `region` argument (and the
+`HEALTH_DEFAULT_REGION` constant) are removed — with a scalar region every environment in a
+monitor had to share a region. The cron `parameters` JSON therefore replaces the
+`elasticBeanstalkEnvironmentNames` + `region` keys with a single `environments` object
+(parameters are spread as **named** args, so the JSON key must match the parameter name):
+
+```json
+{
+  "awsAccountId": "654654170868",
+  "environments": {
+    "us-east-1": ["env-a"],
+    "us-west-2": ["env-b"],
+    "eu-west-1": ["env-c"]
+  },
+  "oneuptimeUrl": "<push URL — credential, not stored here>"
+}
+```
+
+**Credential-reuse pattern (assume once, reuse across regions):** the method calls
+`_Component_Aws_Workloads::assumeCredentials($awsAccountId)` **once** (STS creds are
+region-agnostic) and then constructs **one `ElasticBeanstalkClient` per region reusing those
+same credentials** — rather than calling the per-region `client()` helper repeatedly. Prefer
+this shape whenever one cron touches several regions of a single account: one assume-role
+round-trip, N clients. The OneUptime payload now carries a per-environment `region` field
+plus a top-level `regions[]` array, and the WorkerJobs summary uses `name@region=status`.
+
+The helper adoption was captured earlier: the prior inline STS/credential code and the
+`HEALTH_ASSUME_ROLE_NAME` / `HEALTH_ASSUME_ROLE_SESSION` constants were removed in favor of
+`_Component_Aws_Workloads` + the `[cloud]` config keys. The prior `CheckBeanstalks()` action
+was renamed `ElasticBeanstalkInstances()` (dbchanges2 `Core/2026-08-10c` updates the CronJobs
+action name; `Core/2026-08-10d` seeds the parameterized `ElasticBeanstalkHealth` cron row,
+`isActive=0`, and now carries the `environments`-map sample parameters).
 
 ## Legacy static key — being retired
 
@@ -124,8 +153,25 @@ their only home.
 - Config keys are optional by design (in-code defaults), so a missing `[cloud]`
   `workloads_role_*` key silently uses `WorkloadsRuntime` / `worker2-workloads` — set them
   explicitly in prod ini to override.
+- **`$environments` must be typed `object|array`, not `array`.** The cron dispatcher casts only
+  the top level of `CronJobs.parameters` to an array, so this nested JSON **object** arrives as a
+  PHP `stdClass` and a strict `array` type throws a `TypeError` at dispatch. Declare it
+  `object|array` and `(array)`-cast at the top. General rule for any object-valued cron param —
+  see [creating-worker-actions.md](./creating-worker-actions.md).
 
 ## Change history
+- 2026-08-11 — Noted that `ElasticBeanstalkHealth`'s `$environments` must be typed `object|array`
+  (not `array`): the nested JSON object arrives as `stdClass` because the dispatcher casts only
+  the top level of `CronJobs.parameters`, so a strict `array` throws a `TypeError` at dispatch.
+  Cross-referenced the general rule in creating-worker-actions.md. (jcardinal)
+- 2026-08-11 — `ElasticBeanstalkHealth` signature changed to
+  `(string $awsAccountId, array $environments, string $oneuptimeUrl)`: `$environments` is a
+  region → env-names map, so one monitor can watch EB environments across multiple regions
+  of one account. Removed the flat `elasticBeanstalkEnvironmentNames` list, the scalar
+  `region` arg, and the `HEALTH_DEFAULT_REGION` constant; cron `parameters` JSON now uses a
+  single `environments` object. Recorded the assume-once/reuse-credentials-across-regions
+  pattern (one `assumeCredentials()`, one `ElasticBeanstalkClient` per region) and the new
+  per-environment `region` + top-level `regions[]` payload fields. (jcardinal)
 - 2026-08-10 — Created. Added `_Component_Aws_Workloads` as the standard cross-account AWS
   access helper (instance-role → per-account `WorkloadsRuntime` STS assume-role), documented
   the three-account role model and `[cloud]` config keys, and recorded that the legacy static

package/package.json

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