Release/v1.0.0 beta.27

.claude/skills/kaizen-research/SKILL.md

@@ -25,8 +25,7 @@ Friday early morning (~6am MT). `kaizen-review-prep` runs ~2 hours later (~8am M
 ### External (web — last 7 days unless noted)
 
 1. **AWS Bedrock + AgentCore "What's New"**
-   - https://aws.amazon.com/about-aws/whats-new/recent/feed/
-   - https://aws.amazon.com/bedrock/whats-new/
+   - https://aws.amazon.com/about-aws/whats-new/recent/feed/ (canonical AWS What's New RSS — filter entries for Bedrock/AgentCore)
    - https://aws.amazon.com/blogs/machine-learning/ (filter: bedrock, agentcore)
    - Filter to: Bedrock, AgentCore, Bedrock Agents, Knowledge Bases, Guardrails, model availability/region/quota changes.
 
@@ -71,25 +70,24 @@ Friday early morning (~6am MT). `kaizen-review-prep` runs ~2 hours later (~8am M
 
 6. **Agent harness patterns**
    - https://www.anthropic.com/engineering (Claude Code, agent design posts)
-   - https://docs.claude.com/en/docs/claude-code/release-notes
+   - https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
    - LangChain / LlamaIndex / Pydantic-AI release notes — for ideas, not adoption.
 
 7. **AWS Bedrock pricing + quota**
    - https://aws.amazon.com/bedrock/pricing/
    - Note any model price/quota changes that could shift architecture choices in this repo (e.g., model selection in `inference_api`).
 
 8. **AgentCore SDK / starter-toolkit issues**
-   - https://github.com/aws/amazon-bedrock-agentcore-sdk-python/issues
-   - https://github.com/aws/amazon-bedrock-agentcore-starter-toolkit/issues
+   - https://github.com/aws/bedrock-agentcore-sdk-python/issues
+   - https://github.com/aws/bedrock-agentcore-starter-toolkit/issues
    - Early-signal bugs/limits other users hit before we do.
 
 9. **Community signal (filtered)**
    - HN search: `site:news.ycombinator.com bedrock OR agentcore OR strands OR "claude code"` (last 7 days)
    - r/LocalLLaMA, r/MachineLearning — agent-harness critiques and patterns surface here before vendor blogs.
 
-10. **Anthropic cookbook + courses**
+10. **Anthropic cookbook**
     - https://github.com/anthropics/anthropic-cookbook
-    - https://github.com/anthropics/courses
     - Worked examples often outpace docs — especially for caching, tool use, and agent loops.
 
 11. **Seasonal sources** (only when in window)

.github/ACTIONS-REFERENCE.md

@@ -29,6 +29,10 @@ GitHub provides two mechanisms for storing configuration values:
 | CDK_APP_API_ENABLED | Variable | No | `true` | App API | Enable/disable App API stack deployment |
 | CDK_APP_API_MAX_CAPACITY | Variable | No | `10` | Infrastructure, App API | Maximum App API tasks for auto-scaling |
 | CDK_APP_API_MEMORY | Variable | No | `1024` | Infrastructure, App API | Memory (MB) for App API ECS task (512, 1024, 2048, 4096, 8192) |
+| CDK_ARTIFACTS_CERTIFICATE_ARN | Variable | No | None | Artifacts | ACM certificate ARN that covers `artifacts.{CDK_DOMAIN_NAME}`. **Must be in `us-east-1`** regardless of deployment region. Required when `CDK_ARTIFACTS_ENABLED=true`. Reuse `CDK_FRONTEND_CERTIFICATE_ARN` **only when `CDK_DOMAIN_NAME` is the apex** — TLS wildcards are one label deep, so `*.example.com` covers `artifacts.example.com` but not `artifacts.alpha.example.com`. When `CDK_DOMAIN_NAME` is a subdomain, issue a dedicated `us-east-1` cert for `*.{CDK_DOMAIN_NAME}`. |
+| CDK_ARTIFACTS_ENABLED | Variable | No | `false` | Artifacts, Infrastructure, App API, Inference API, Frontend | Enable iframe-isolated artifact rendering. Toggling on provisions a DDB metadata table, S3 content bucket, CloudFront + Lambda render service, and the supporting IAM grants / env vars on the consumer stacks. |
+| CDK_ARTIFACTS_EXTRA_FRAME_ANCESTORS | Variable | No | None | Artifacts | Comma-separated extra origins (beyond `https://{CDK_DOMAIN_NAME}`) permitted to embed artifact iframes via CSP `frame-ancestors` — e.g. `http://localhost:4200` for a local SPA pointed at this deployment. Applied to both the CloudFront response-headers policy and the render Lambda's CSP. **Leave unset in production**: every listed origin can frame users' artifacts (still render-token gated, but a real loosening on a shared environment). |
+| CDK_ARTIFACTS_RETENTION_DAYS | Variable | No | `90` | Artifacts | Days after which soft-deleted artifacts (objects tagged `lifecycle-class=deleted`) are reaped by the S3 lifecycle rule. |
 | CDK_ASSISTANTS_CORS_ORIGINS | Variable | No | None | Infrastructure | Additional CORS origins for the assistants module only (appended to global CORS origins) |
 | CDK_AWS_ACCOUNT | Variable | Yes | None | All | 12-digit AWS account ID for CDK deployment |
 | CDK_CERTIFICATE_ARN | Variable | No | None | Infrastructure | ACM certificate ARN for HTTPS on ALB |

.github/README-ACTIONS.md

@@ -12,6 +12,7 @@ Deploy a production-ready multi-agent AI platform to your AWS account in about 4
 |-----------|-------------|
 | **VPC + ALB + ECS** | Networking, load balancer, and container orchestration |
 | **Fine-Tuning** *(optional)* | SageMaker training/inference infrastructure, S3 artifact storage, DynamoDB job tracking |
+| **Artifacts** *(optional)* | Iframe-isolated artifact rendering (DDB metadata, S3 content, CloudFront at `artifacts.{domain}`, Lambda render service) |
 | **RAG Ingestion** | Document ingestion pipeline for retrieval-augmented generation |
 | **Inference API** | Strands Agent runtime powered by AWS Bedrock AgentCore |
 | **App API** | Backend REST API for chat, sessions, admin, and auth |

.github/copilot-instructions.md

@@ -0,0 +1,84 @@
+# Copilot Instructions — AgentCore Public Stack
+
+Production multi-agent conversational AI platform built on AWS Bedrock AgentCore + Strands Agents. Monorepo with four top-level packages: `backend/` (Python 3.13, FastAPI), `frontend/ai.client/` (Angular 21 + Analog.js), `infrastructure/` (AWS CDK, TypeScript), and `scripts/`.
+
+Authoritative deeper docs: `CLAUDE.MD` (architecture), `CONTRIBUTING.md` (setup), `.kiro/steering/` and `.claude/skills/` (topic-specific patterns — CDK, Tailwind, Angular signals, CORS, release notes, versioning).
+
+## Build, Test, Lint
+
+### Backend (`cd backend`)
+```bash
+uv sync --extra agentcore --extra dev
+uv run python -m pytest tests/ -v
+uv run python -m pytest tests/path/to/test_file.py::test_name -v   # single test
+uv run black src/ && uv run ruff check src/ && uv run mypy src/
+# Run services locally:
+cd src/apis/app_api && uv run python main.py        # port 8000
+cd src/apis/inference_api && uv run python main.py  # port 8001
+```
+
+### Frontend (`cd frontend/ai.client`)
+```bash
+npm ci
+npm run start                          # dev server on 4200
+npm test                               # Vitest via Analog.js
+npx vitest run path/to/file.spec.ts    # single test file
+npx eslint src/ && npx prettier --check src/
+```
+
+### Infrastructure (`cd infrastructure`)
+```bash
+npm ci && npm run build
+npx cdk synth                          # validates stacks
+npx cdk deploy --all
+npm test -- test/stack-dependencies.test.ts   # verifies new stacks are registered
+```
+
+## Architecture — the big picture
+
+- **Three independent backend consumers** of `apis.shared`: `app_api`, `inference_api`, and `agents/`. They must **never import from each other** — only from `apis.shared`. Enforced by `backend/tests/architecture/test_import_boundaries.py`.
+- **Inference API runs inside an AgentCore Runtime container.** The runtime data plane only proxies `POST /invocations` and `GET /ping` — any other route returns 404 in cloud (works locally because `localhost:8001` bypasses the gateway). User-facing CRUD endpoints **belong in app-api**, not inference-api. To get workload context on app-api, use the `AGENTCORE_RUNTIME_WORKLOAD_NAME` mint fallback in `apis/shared/oauth/agentcore_identity.py`.
+- **Deploy order** (cross-stack SSM references): Infrastructure → (Gateway, RAG Ingestion, SageMaker Fine-Tuning, Artifacts, MCP Sandbox in parallel) → Inference API → App API → Frontend. App API reads `runtime-workload-identity-name` from SSM, published by Inference API.
+- **Errors stream as assistant messages over SSE**, not HTTP error codes. See SSE event table in `CLAUDE.MD` (`message_start`, `content_block_*`, `tool_use`/`tool_result`, `ui_resource`, `stream_error`, `oauth_required`, `compaction`, `done`).
+- **Multi-protocol tools:** direct/AWS-SDK tools live in `agents/main_agent/tools/`; remote tools come via MCP+SigV4 (Gateway Lambda) or A2A (Runtime). A2A is currently **client-only**; if exposing an A2A server, `capabilities` must include `streaming=True` or clients hang.
+- **Frontend is signal-based** throughout (`signal()`, `computed()`). API shapes are defined by backend routes; matching TS interfaces must be updated in the same PR as breaking backend changes.
+
+## Conventions specific to this repo
+
+- **Auth on `apis/app_api/` routes** uses `Depends(get_current_user_from_session)` (cookie-based) or `Depends(require_admin)`. The SPA sends an httpOnly session cookie, **not** `Authorization: Bearer`. Bearer-only deps on user-facing routes cause a 401 → redirect loop. Exceptions: `auth/api_keys/` (X-API-Key) and `voice/` (voice-ticket cookie) — do not template off these.
+- **Admin endpoints** go under `/admin/<domain>/`, user-facing under `/<domain>/`.
+- **Exact dependency pins only** — no `^`, `~`, or `>=` anywhere (Python, npm, CDK).
+- **Never install new packages without explicit user approval.**
+- **Branch from `develop`**, never `main`. PRs target `develop`; `main` advances only via squash-merge releases. Branch naming: `feature/<short-description>`. Sign commits with `git commit -s` (DCO).
+- **Conventional commits** (`feat:`, `fix:`, `chore:`, ...), one logical change per commit.
+- **No `print()` in backend** — use `logging`. Python: `snake_case` / `PascalCase`, type hints required. TS: strict mode, no `any` unless unavoidable.
+
+## File placement
+
+| Change | Location |
+|---|---|
+| New API route | `backend/src/apis/app_api/<domain>/` |
+| Admin endpoint | `backend/src/apis/app_api/admin/<domain>/` |
+| New agent tool | `backend/src/agents/main_agent/tools/` + register in `__init__.py` |
+| Shared backend code | `backend/src/apis/shared/<domain>/` |
+| Lambda for an infra stack | `backend/src/lambdas/<lambda-name>/` (not part of `apis/` boundary) |
+| Angular page | `frontend/ai.client/src/app/<feature>/` |
+| New CDK stack | `infrastructure/lib/<stack-name>-stack.ts` — also register in `test/stack-dependencies.test.ts` with a tier, add `scripts/stack-<name>/`, add a workflow under `.github/workflows/`, update `.github/docs/deploy/step-04-deploy.md` |
+
+## Debugging cheatsheet
+
+- **Tool not appearing:** check `__init__.py` export, RBAC permissions, `enabled_tools`, ToolRegistry.
+- **Session not persisting:** check AgentCore Memory config, `session_id`, `TurnBasedSessionManager` flush.
+- **SSE stream disconnecting:** check the 600s timeout, client connection, quota-exceeded events.
+- **Local inference-api route works, cloud returns 404:** the route isn't `/invocations` or `/ping` — move it to app-api (see Architecture).
+
+## Topic deep-dives
+
+Before non-trivial work in these areas, consult the matching skill/steering doc:
+
+- CDK stacks/constructs → `.claude/skills/cdk-infrastructure/` and `.kiro/steering/cdk-*.md`
+- Angular components/signals → `.claude/skills/angualar-best-practices/` and `.kiro/steering/angular-*.md`
+- Tailwind v4 / a11y → `.claude/skills/tailwind-ui/` and `.kiro/steering/tailwind-*.md`
+- CORS across stacks → `.claude/skills/cors-deployment/SKILL.md`
+- Release notes / CHANGELOG → `.claude/skills/release-notes/SKILL.md`
+- Version bumps → `.claude/skills/versioning/SKILL.md`

.github/docs/deploy/step-02-aws-setup.md

@@ -133,6 +133,13 @@ This allows the certificate to cover subdomains like `api.example.com` and `app.
 - `ALB Certificate ARN` (e.g. `arn:aws:acm:us-west-2:123456789012:certificate/abc-123`)
 - `CloudFront Certificate ARN` (e.g. `arn:aws:acm:us-east-1:123456789012:certificate/def-456`)
 
+> [!IMPORTANT]
+> **If you plan to enable the optional Artifacts stack, mind the wildcard depth.** A TLS wildcard covers **exactly one** label — `*.example.com` matches `artifacts.example.com` but **not** `artifacts.alpha.example.com`.
+> - If `CDK_DOMAIN_NAME` is your **apex** (e.g. `example.com`), the artifact origin is `artifacts.example.com` and the existing `*.example.com` CloudFront cert covers it — reuse that cert ARN, no third certificate needed.
+> - If `CDK_DOMAIN_NAME` is **already a subdomain** (e.g. `alpha.example.com`), the artifact origin is `artifacts.alpha.example.com`, which `*.example.com` does **not** cover. Issue a dedicated `us-east-1` cert for `*.alpha.example.com` (or exactly `artifacts.alpha.example.com`) and use that ARN for `CDK_ARTIFACTS_CERTIFICATE_ARN`.
+>
+> Verify before deploying: `aws acm describe-certificate --region us-east-1 --certificate-arn <arn> --query 'Certificate.SubjectAlternativeNames'` should list a SAN that matches `artifacts.{CDK_DOMAIN_NAME}`.
+
 <details>
 <summary>My certificate is stuck in "Pending validation"</summary>
 

.github/docs/deploy/step-03-github-config.md

@@ -100,6 +100,9 @@ This prefix is prepended to all AWS resource names to avoid conflicts. Use somet
 | Variable Name | Default | Description |
 |---------------|---------|-------------|
 | `CDK_FINE_TUNING_ENABLED` | `false` | Set to `true` to enable the SageMaker Fine-Tuning stack. Must be set before running the fine-tuning deployment workflow in Step 4. |
+| `CDK_ARTIFACTS_ENABLED` | `false` | Set to `true` to enable iframe-isolated artifact rendering. Provisions the artifacts CloudFront origin, DDB table, S3 bucket, and Lambda. Requires `CDK_ARTIFACTS_CERTIFICATE_ARN`. |
+| `CDK_ARTIFACTS_CERTIFICATE_ARN` | — | ACM certificate ARN that covers `artifacts.{CDK_DOMAIN_NAME}`. **Must be in `us-east-1`** (CloudFront requirement). Reuse `CDK_FRONTEND_CERTIFICATE_ARN` **only if `CDK_DOMAIN_NAME` is your apex** (a `*.example.com` cert covers `artifacts.example.com`). If `CDK_DOMAIN_NAME` is itself a subdomain (e.g. `alpha.example.com`), wildcards are one label deep so `*.example.com` does **not** cover `artifacts.alpha.example.com` — issue a dedicated `us-east-1` cert for `*.alpha.example.com`. See [Step 2c](./step-02-aws-setup.md#2c-create-acm-certificates). |
+| `CDK_ARTIFACTS_EXTRA_FRAME_ANCESTORS` | — | Comma-separated extra origins (beyond `https://{CDK_DOMAIN_NAME}`) allowed to embed artifact iframes via CSP `frame-ancestors` — applied to both the CloudFront response-headers policy and the render Lambda. Set to `http://localhost:4200` to point a local SPA at this deployment. **Leave unset in production**: every listed origin can frame your users' artifacts (still render-token gated, but a real loosening on a shared environment). Prefer a one-off `cdk deploy '*ArtifactsStack*'` with this exported over committing it as a CI variable. |
 
 ---