toga-ai 1.0.319 → 1.0.320

package/knowledge/1.0/apps/tools/INDEX.md

@@ -7,6 +7,6 @@
 | [Tools MVC — Routing, CSRF & App_Database Access Patterns](features/mvc-data-access-patterns.md) | The load-bearing 1.0 (`App_`) framework conventions a developer needs when adding a page to the Tools app — URL routing, CSRF, and DB access through `App_Databa | tools/_/app/nav.php, tools/mvc/get.php |
 | [Tools Persona-Gated Navigation (App_Nav)](features/persona-gated-navigation.md) | `App_Nav` is the Tools app's two-level, **persona-gated** navigation. | tools/_/app/nav.php, tools/mvc/get.php |
 | [Tools SAML SSO Consumer & Persona-Gated Auth (App_Auth)](features/saml-sso-auth.md) | `App_Auth` is the Tools app's authentication layer: it consumes the SAML gateway `?saml=` handoff (see the 2.0 SAML downstream integration contract), establishe | tools/_/app/auth.php, tools/mvc/sso/initiate/get.php, tools/mvc/sso/get.php, tools/mvc/login/get.php, tools/mvc/login/post.php, tools/mvc/logout/get.php, tools/mvc/get.php, tools/config.production.ini, tools/config.local.ini |
-| [Talos Knowledge Base Admin UI (KB Documents + Vocabulary)](features/talos-kb-documents-admin.md) | A Tools (1.0) admin UI to browse/fix the Talos knowledge-base documents and manage the transcript-cleanup vocabulary — without a deploy. | tools/mvc/talos/kb-documents/get.php, tools/mvc/talos/kb-documents/post.php, tools/mvc/talos/vocabulary/get.php, tools/mvc/talos/vocabulary/post.php, tools/_/app/talos/s3.php, tools/_/app/worker.php, tools/_/app/nav.php, tools/config.production.ini, tools/config.alpha.ini |
+| [Talos Knowledge Base Admin UI (KB Documents + Vocabulary)](features/talos-kb-documents-admin.md) | A Tools (1.0) admin UI to browse/fix the Talos knowledge-base documents and manage the transcript-cleanup vocabulary — without a deploy. | tools/mvc/talos/kb-documents/get.php, tools/mvc/talos/kb-documents/post.php, tools/mvc/talos/knowledge-bases/post.php, tools/mvc/talos/vocabulary/get.php, tools/mvc/talos/vocabulary/post.php, tools/_/app/talos/s3.php, tools/_/app/talos/bedrock.php, tools/_/app/worker.php, tools/_/app/nav.php, tools/config.production.ini, tools/config.alpha.ini, tools/.platform/httpd/conf.d/timeouts.conf |
 | [Talos Pricing UI (Onboarding, Dashboard, Benchmarks, Cost Factors + Estimator)](features/talos-pricing-ui.md) | The 1.0 (tools app) face of the **Talos Pricing Platform** — a "Talos Pricing" nav folder with four pages plus a client-side estimate engine. | tools/_/app/nav.php, tools/_/app/talos/estimator.php, tools/mvc/talos/onboarding/get.php, tools/mvc/talos/onboarding/post.php, tools/mvc/talos/pricing/get.php, tools/mvc/talos/benchmarks/get.php, tools/mvc/talos/factors/get.php, tools/mvc/talos/factors/post.php, tools/assets/css/style.css |
 | [Deploying Tools to Elastic Beanstalk (PHP 8.5 / Amazon Linux 2023)](workflows/deploy-to-elastic-beanstalk-al2023.md) | How the **Tools** 1.0 app boots on Elastic Beanstalk running `PHP 8.5 on 64bit Amazon Linux 2023/4.13.1 (aarch64)`. | tools/.ebextensions/004_http_to_https.config, tools/.ebextensions/006_mount-s3fs.config, tools/.ebextensions/007_setup_export_cache_folders.config, tools/.ebextensions/008_setup_ldap.config, tools/.ebextensions/009_setup_phpini.config, tools/.ebextensions/020_setup_git_libraries.config, tools/.ebextensions/050_register_instance_to_shared_application_load_balancer.config, tools/ebs/git.json |

package/knowledge/1.0/apps/tools/features/talos-kb-documents-admin.md

@@ -6,18 +6,21 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-07-09
+updated: 2026-07-13
 owners: [jcardinal]
 files:
   - tools/mvc/talos/kb-documents/get.php
   - tools/mvc/talos/kb-documents/post.php
+  - tools/mvc/talos/knowledge-bases/post.php
   - tools/mvc/talos/vocabulary/get.php
   - tools/mvc/talos/vocabulary/post.php
   - tools/_/app/talos/s3.php
+  - tools/_/app/talos/bedrock.php
   - tools/_/app/worker.php
   - tools/_/app/nav.php
   - tools/config.production.ini
   - tools/config.alpha.ini
+  - tools/.platform/httpd/conf.d/timeouts.conf
 related:
   - ./mvc-data-access-patterns.md
   - ./persona-gated-navigation.md
@@ -73,6 +76,33 @@ so they displayed **double-encoded** (e.g. "Grand & Toy"). `vocabulary/post.
 `html_entity_decode()`s values on save so the DB stores **raw** text; `vocabulary/get.php`
 already escapes once at display. Do not re-add encoding on save.
 
+### `POST /talos/knowledge-bases` — create a new KB (synchronous provisioning)
+
+Admin action that provisions a brand-new Talos knowledge base end to end in **one
+synchronous request**: creates the S3 prefix, creates the Bedrock KB and **waits for it to
+reach `ACTIVE`**, creates the Bedrock data source (`MANAGED_KNOWLEDGE_BASE_CONNECTOR`), and
+inserts 2 MySQL (`Team.KnowledgeBases`, `Team.VectorIndexes`) + 2 Postgres rows. This flow
+**stays synchronous by design** — moving it to worker2/SQS async was explicitly rejected;
+the fix path is to raise timeouts, never to background the work.
+
+The handler is **best-effort with no rollback**: on a mid-flow failure it stops and returns
+a `steps[]` report **without tearing down** already-created AWS resources (see Gotchas —
+orphaned KB).
+
+**`App_Talos_Bedrock`** (`_/app/talos/bedrock.php`) — Bedrock Agent client:
+- `waitForKnowledgeBaseActive()` polls `getKnowledgeBase` every `WAIT_INTERVAL_SECONDS` (3s)
+  up to **`WAIT_MAX_SECONDS` = 300** (raised from 90; MANAGED KBs were observed taking ~3 min
+  to leave `CREATING`). Exits immediately on `ACTIVE`/`FAILED`, so fast activations are
+  unaffected. 300s sits well under the 900s Apache/PHP ceiling.
+- `createDataSource()` — `connectorParameters` for `managedKnowledgeBaseConnectorConfiguration`
+  is a **`Document` shape (free-form JSON)** in the AWS PHP SDK model and **must be passed as a
+  native PHP array** so the SDK serializes a JSON *object*. Passing a pre-`json_encode()`d
+  **string** fails `ValidationException "Invalid connector parameters format"`. Working object
+  shape (matches the craftex data source):
+  `{type:S3, filterConfiguration:{maxFileSizeInMegaBytes:"500",
+  inclusionPrefixes:["development-team/{slug}/approved/"]}, connectionConfiguration:{bucketName:togaiq,
+  bucketOwnerAccountId:654654170868, bucketArn:arn:aws:s3:::togaiq}, aclEnabled:false, version:"1"}`.
+
 ## Helpers
 
 - **`App_Talos_S3`** (`_/app/talos/s3.php`) — S3 client; list KB slugs; list/count approved
@@ -116,11 +146,45 @@ already escapes once at display. Do not re-add encoding on save.
   within the same bucket; move/edit copy via get+put.
 - **Move/edit re-sync must be one `SyncKb("source,dest")` job**, not two parallel jobs — Bedrock
   allows only one in-flight ingestion per KB and parallel syncs race.
+- **KB create is synchronous and long (~minutes).** It must run under a raised timeout — see
+  the EB Apache 504 gotcha below. Do **not** re-architect it to worker2/SQS (explicitly
+  rejected).
+- **EB AL2023 PHP platform → 60s default proxy timeout → 504.** The tools app runs on Elastic
+  Beanstalk PHP 8.5 / Amazon Linux 2023, where **Apache proxies to php-fpm via
+  `mod_proxy_fcgi`** and the proxy read timeout defaults to `Timeout` = **60s**. A long
+  synchronous request (KB create) returns **504 after exactly 60s**. Raising the **ALB idle
+  timeout does not help** (it's upstream of Apache), and PHP `set_time_limit(900)` is
+  irrelevant (Apache emits the 504, and on Linux `max_execution_time` does not count time
+  blocked in network I/O). Fix: an EB platform Apache drop-in at
+  **`.platform/httpd/conf.d/timeouts.conf`** setting `Timeout 900` and **`ProxyTimeout 900`**
+  (`ProxyTimeout` is the `mod_proxy_fcgi` read timeout; matches the framework's
+  `set_time_limit(900)`). Applied on deploy.
+- **php-fpm `request_terminate_timeout` can still kill the request.** If
+  `/etc/php-fpm.d/www.conf`'s `request_terminate_timeout` is ever set to 60 it terminates the
+  request regardless of Apache — it must be `0` or `>= 900`.
+- **`get-data-source` echoes `connectorParameters` back as a quoted STRING** even though the
+  create input must be a JSON **object** — the GET representation is misleading and does NOT
+  indicate the required input shape.
+- **KB create has no rollback → orphaned KB risk.** A failure at the data-source step leaves an
+  orphaned Bedrock KB with **no DB rows** (`Team.KnowledgeBases`/`VectorIndexes`/Postgres never
+  inserted). Blindly re-running with the same name creates a **duplicate** Bedrock KB (Bedrock
+  allows same-name KBs with new ids). After a failed create: either
+  `aws bedrock-agent delete-knowledge-base` the orphan and re-run clean, or finish the DB rows
+  manually.
 - No new secret literals introduced; credentials live in the config sections above (documented by
-  section/account, never by value).
+  section/account, never by value). AWS account id `654654170868`, bucket `togaiq`, and the KB
+  execution-role ARN are non-secret resource identifiers.
 
 ## Change history
 
+- 2026-07-13 — Added the **synchronous KB-create flow** (`POST /talos/knowledge-bases`) via new
+  `App_Talos_Bedrock` helper. Fixed the **504 at 60s**: EB AL2023 PHP = Apache→php-fpm over
+  `mod_proxy_fcgi` with a 60s default proxy read timeout; added
+  `.platform/httpd/conf.d/timeouts.conf` (`Timeout 900` + `ProxyTimeout 900`). Raised
+  `WAIT_MAX_SECONDS` 90→300 (MANAGED KBs take ~3 min to go `ACTIVE`). Fixed `createDataSource`
+  `ValidationException` by passing `connectorParameters` as a native array (`Document` shape),
+  not a `json_encode`d string. Documented the no-rollback orphaned-KB caveat and the misleading
+  `get-data-source` string echo. Flow stays synchronous (worker2 async rejected). (jcardinal)
 - 2026-07-09 — Fixed `App_Talos_S3::sanitizeTitle()` to convert `/`,`\` to hyphens (was
   spaces) so a slashed meeting title no longer creates a stray S3 sub-folder — matches
   worker2's `filenameSafeTitle()`; `updateApprovedDocument()` already renames the S3 object and

package/package.json

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