chore(docs): update docs

bgagent · bgagent · commit 4daf6668abe1 · 2026-05-05T19:54:34.000-05:00
diff --git a/docs/design/COST_MODEL.md b/docs/design/COST_MODEL.md
@@ -13,14 +13,17 @@ These costs are incurred regardless of task volume:
 | NAT Gateway (1×) | ~$32/month | Fixed hourly cost + data processing. Single AZ (see [COMPUTE.md  - Network architecture](./COMPUTE.md)). |
 | VPC Interface Endpoints (7×, 2 AZs) | ~$102/month | $0.01/hr × 7 endpoints × 2 AZs × 730 hrs. |
 | VPC Flow Logs | ~$3/month | CloudWatch ingestion. |
-| DynamoDB (on-demand, idle) | ~$0/month | Pay-per-request; no cost when idle. |
+| DynamoDB (on-demand, idle) | ~$0/month | Pay-per-request; 6 tables (Tasks, Events, Nudges, UserConcurrency, Webhooks, Repo). No cost when idle. |
+| S3 Trace Artifacts bucket (idle) | ~$0/month | 7-day lifecycle auto-expires objects; no cost when no traces are stored. |
+| EventBridge reconciler rule | <$0.01/month | Invokes Lambda every 5 min (288/day). Rule itself is free; Lambda invocation is the cost (see below). |
+| Stranded task reconciler Lambda (idle) | <$0.01/month | 288 invocations/day × 256 MB × ~100 ms avg (early exit when no stranded tasks). ~$0.005/month total (requests + duration). |
 | CloudWatch Logs retention | ~$1–5/month | Depends on log volume. 90-day retention. |
 | API Gateway (idle) | ~$0/month | Pay-per-request. |
-| **Total baseline** | **~$140–150/month** | |
+| **Total baseline** | **~$140–150/month** | Reconciler adds negligible cost; VPC networking remains dominant. |
 
 ### Scale-to-zero characteristics
 
-Most platform components are fully serverless and incur zero cost when idle: DynamoDB (PAY_PER_REQUEST), Lambda, API Gateway, ECS Fargate (cluster is free, when enabled), AgentCore Runtime (per-session), Bedrock (per-token), and Cognito (free tier). The always-on cost floor (~$140–150/month) is dominated by VPC networking infrastructure (NAT Gateway + 7 interface endpoints across 2 AZs) which is required for private subnet connectivity to AWS services and GitHub. See the [Deployment guide](../guides/DEPLOYMENT_GUIDE.md) for the full scale-to-zero breakdown.
+Most platform components are fully serverless and incur zero cost when idle: DynamoDB (PAY_PER_REQUEST, 6 tables), Lambda, API Gateway, S3 (trace artifacts auto-expire in 7 days), SQS (fanout DLQ), ECS Fargate (cluster is free, when enabled), AgentCore Runtime (per-session), Bedrock (per-token), and Cognito (free tier). The stranded task reconciler adds <$0.01/month even when idle (288 Lambda invocations/day, early-exit). The always-on cost floor (~$140–150/month) is dominated by VPC networking infrastructure (NAT Gateway + 7 interface endpoints across 2 AZs) which is required for private subnet connectivity to AWS services and GitHub. See the [Deployment guide](../guides/DEPLOYMENT_GUIDE.md) for the full scale-to-zero breakdown.
 
 ## Per-task variable costs
 
@@ -35,10 +38,14 @@ Assuming a typical task: 1–2 hours, Claude Sonnet, ~100K input tokens, ~20K ou
 | **Bedrock tokens (dominant)** | $2–15 | Varies widely by model, task complexity, and turn count. Claude Sonnet: ~$3/M input tokens, ~$15/M output tokens. A 50-turn task with 100K input + 20K output per turn ≈ 5M input + 1M output ≈ $15 + $15 = $30 at list price. Prompt caching reduces this significantly (up to 90% for cache hits). Typical range: $2–15 after caching. |
 | AgentCore Runtime compute | $0.10–0.50 | 2 vCPU / 8 GB for 1–2 hours. Pricing model is per-session based on vCPU-hours and GB-hours. |
 | Lambda orchestrator | <$0.01 | ~10 invocations per task (admission, hydration, polling, finalization). Negligible. |
-| DynamoDB reads/writes | <$0.01 | ~20–50 operations per task (task CRUD, events, counter updates). Negligible. |
+| Lambda fanout consumer | <$0.01 | Triggered per batch of task events (batch size 100, 5 s window). Typically 5–20 invocations per task at 256 MB. Negligible. |
+| Lambda nudge / trace / events | <$0.01 | On-demand per user request. Negligible unless heavily polled. |
+| DynamoDB reads/writes | <$0.01 | ~30–80 operations per task (task CRUD, events, nudges, counter updates). Negligible. |
+| DynamoDB Streams (fanout) | <$0.01 | Stream reads charged per 25 KB. Typical task: ~20–50 event records. Negligible. |
+| S3 trace upload (if `--trace`) | <$0.01 | One PUT per task + storage (gzipped NDJSON, typically 50–500 KB, auto-expires in 7 days). |
 | NAT Gateway data | <$0.01 | GitHub API traffic: clone + push. Small repos: <10 MB. |
 | Custom step Lambdas | $0–0.05 | Only if configured. Per-invocation: ~$0.01 per step. |
-| **Total per task** | **$2–15** | Bedrock tokens dominate (>90% of per-task cost). |
+| **Total per task** | **$2–15** | Bedrock tokens dominate (>90% of per-task cost). New interactive features add <$0.01 per task. |
 
 ### Cost sensitivity analysis
 
diff --git a/docs/guides/DEPLOYMENT_GUIDE.md b/docs/guides/DEPLOYMENT_GUIDE.md
@@ -25,7 +25,7 @@ ECS Fargate is currently **opt-in** -- the `EcsAgentCluster` construct is presen
 
 | Component | Billing Model | Idle Cost |
 |-----------|--------------|-----------|
-| DynamoDB (5 tables) | PAY_PER_REQUEST | $0 |
+| DynamoDB (6 tables) | PAY_PER_REQUEST | $0 |
 | Lambda (all functions) | Per invocation | $0 |
 | API Gateway REST | Per request | $0 |
 | ECS Fargate tasks (when enabled) | Per running task | $0 (cluster is free) |
@@ -59,7 +59,7 @@ For the full cost model including per-task costs, see [COST_MODEL.md](../design/
 |---------|---------|---------------|
 | Bedrock AgentCore Runtime (MicroVMs) | Agent sessions (default) | Yes |
 | ECS Fargate (when enabled) | Agent sessions (opt-in) | Yes |
-| Lambda (Node.js 24, ARM64) | Orchestrator, API handlers, reconciler, custom resources | Yes |
+| Lambda (Node.js 24, ARM64) | Orchestrator, API handlers, fanout consumer, reconcilers, custom resources | Yes |
 
 ### AI/ML
 
@@ -84,8 +84,10 @@ For the full cost model including per-task costs, see [COST_MODEL.md](../design/
 
 | Service | Used By | Scales to Zero |
 |---------|---------|---------------|
-| DynamoDB (5 tables, PAY_PER_REQUEST) | Task state, events, concurrency, webhooks, repo config | Yes |
-| S3 | CDK asset bucket, ECR image layers, FUSE session storage | Minimal |
+| DynamoDB (6 tables, PAY_PER_REQUEST) | Task state, events, nudges, concurrency, webhooks, repo config | Yes |
+| DynamoDB Streams | TaskEventsTable → FanOut Consumer Lambda | Yes |
+| S3 | CDK asset bucket, ECR image layers, FUSE session storage, trace artifacts (7-day lifecycle) | Minimal |
+| SQS (DLQ) | FanOut Consumer dead-letter queue | Yes |
 | Secrets Manager | GitHub PAT, webhook HMAC secrets | **No** (~$0.40/secret/mo) |
 
 ### API / Auth
@@ -96,6 +98,12 @@ For the full cost model including per-task costs, see [COST_MODEL.md](../design/
 | Cognito User Pool | CLI/API authentication | Yes (free tier) |
 | WAF v2 | API Gateway protection (managed rules + rate limiting) | **No** (~$5/mo base) |
 
+### Scheduling
+
+| Service | Used By | Scales to Zero |
+|---------|---------|---------------|
+| EventBridge (scheduled rule) | Stranded task reconciler (every 5 min) | Yes (rule is free; Lambda invocation is the cost) |
+
 ### Observability
 
 | Service | Used By | Scales to Zero |
diff --git a/docs/src/content/docs/architecture/Cost-model.md b/docs/src/content/docs/architecture/Cost-model.md
@@ -17,14 +17,17 @@ These costs are incurred regardless of task volume:
 | NAT Gateway (1×) | ~$32/month | Fixed hourly cost + data processing. Single AZ (see [COMPUTE.md  - Network architecture](/architecture/compute)). |
 | VPC Interface Endpoints (7×, 2 AZs) | ~$102/month | $0.01/hr × 7 endpoints × 2 AZs × 730 hrs. |
 | VPC Flow Logs | ~$3/month | CloudWatch ingestion. |
-| DynamoDB (on-demand, idle) | ~$0/month | Pay-per-request; no cost when idle. |
+| DynamoDB (on-demand, idle) | ~$0/month | Pay-per-request; 6 tables (Tasks, Events, Nudges, UserConcurrency, Webhooks, Repo). No cost when idle. |
+| S3 Trace Artifacts bucket (idle) | ~$0/month | 7-day lifecycle auto-expires objects; no cost when no traces are stored. |
+| EventBridge reconciler rule | <$0.01/month | Invokes Lambda every 5 min (288/day). Rule itself is free; Lambda invocation is the cost (see below). |
+| Stranded task reconciler Lambda (idle) | <$0.01/month | 288 invocations/day × 256 MB × ~100 ms avg (early exit when no stranded tasks). ~$0.005/month total (requests + duration). |
 | CloudWatch Logs retention | ~$1–5/month | Depends on log volume. 90-day retention. |
 | API Gateway (idle) | ~$0/month | Pay-per-request. |
-| **Total baseline** | **~$140–150/month** | |
+| **Total baseline** | **~$140–150/month** | Reconciler adds negligible cost; VPC networking remains dominant. |
 
 ### Scale-to-zero characteristics
 
-Most platform components are fully serverless and incur zero cost when idle: DynamoDB (PAY_PER_REQUEST), Lambda, API Gateway, ECS Fargate (cluster is free, when enabled), AgentCore Runtime (per-session), Bedrock (per-token), and Cognito (free tier). The always-on cost floor (~$140–150/month) is dominated by VPC networking infrastructure (NAT Gateway + 7 interface endpoints across 2 AZs) which is required for private subnet connectivity to AWS services and GitHub. See the [Deployment guide](/getting-started/deployment-guide) for the full scale-to-zero breakdown.
+Most platform components are fully serverless and incur zero cost when idle: DynamoDB (PAY_PER_REQUEST, 6 tables), Lambda, API Gateway, S3 (trace artifacts auto-expire in 7 days), SQS (fanout DLQ), ECS Fargate (cluster is free, when enabled), AgentCore Runtime (per-session), Bedrock (per-token), and Cognito (free tier). The stranded task reconciler adds <$0.01/month even when idle (288 Lambda invocations/day, early-exit). The always-on cost floor (~$140–150/month) is dominated by VPC networking infrastructure (NAT Gateway + 7 interface endpoints across 2 AZs) which is required for private subnet connectivity to AWS services and GitHub. See the [Deployment guide](/getting-started/deployment-guide) for the full scale-to-zero breakdown.
 
 ## Per-task variable costs
 
@@ -39,10 +42,14 @@ Assuming a typical task: 1–2 hours, Claude Sonnet, ~100K input tokens, ~20K ou
 | **Bedrock tokens (dominant)** | $2–15 | Varies widely by model, task complexity, and turn count. Claude Sonnet: ~$3/M input tokens, ~$15/M output tokens. A 50-turn task with 100K input + 20K output per turn ≈ 5M input + 1M output ≈ $15 + $15 = $30 at list price. Prompt caching reduces this significantly (up to 90% for cache hits). Typical range: $2–15 after caching. |
 | AgentCore Runtime compute | $0.10–0.50 | 2 vCPU / 8 GB for 1–2 hours. Pricing model is per-session based on vCPU-hours and GB-hours. |
 | Lambda orchestrator | <$0.01 | ~10 invocations per task (admission, hydration, polling, finalization). Negligible. |
-| DynamoDB reads/writes | <$0.01 | ~20–50 operations per task (task CRUD, events, counter updates). Negligible. |
+| Lambda fanout consumer | <$0.01 | Triggered per batch of task events (batch size 100, 5 s window). Typically 5–20 invocations per task at 256 MB. Negligible. |
+| Lambda nudge / trace / events | <$0.01 | On-demand per user request. Negligible unless heavily polled. |
+| DynamoDB reads/writes | <$0.01 | ~30–80 operations per task (task CRUD, events, nudges, counter updates). Negligible. |
+| DynamoDB Streams (fanout) | <$0.01 | Stream reads charged per 25 KB. Typical task: ~20–50 event records. Negligible. |
+| S3 trace upload (if `--trace`) | <$0.01 | One PUT per task + storage (gzipped NDJSON, typically 50–500 KB, auto-expires in 7 days). |
 | NAT Gateway data | <$0.01 | GitHub API traffic: clone + push. Small repos: <10 MB. |
 | Custom step Lambdas | $0–0.05 | Only if configured. Per-invocation: ~$0.01 per step. |
-| **Total per task** | **$2–15** | Bedrock tokens dominate (>90% of per-task cost). |
+| **Total per task** | **$2–15** | Bedrock tokens dominate (>90% of per-task cost). New interactive features add <$0.01 per task. |
 
 ### Cost sensitivity analysis
 
diff --git a/docs/src/content/docs/getting-started/Deployment-guide.md b/docs/src/content/docs/getting-started/Deployment-guide.md
@@ -29,7 +29,7 @@ ECS Fargate is currently **opt-in** -- the `EcsAgentCluster` construct is presen
 
 | Component | Billing Model | Idle Cost |
 |-----------|--------------|-----------|
-| DynamoDB (5 tables) | PAY_PER_REQUEST | $0 |
+| DynamoDB (6 tables) | PAY_PER_REQUEST | $0 |
 | Lambda (all functions) | Per invocation | $0 |
 | API Gateway REST | Per request | $0 |
 | ECS Fargate tasks (when enabled) | Per running task | $0 (cluster is free) |
@@ -63,7 +63,7 @@ For the full cost model including per-task costs, see [COST_MODEL.md](/architect
 |---------|---------|---------------|
 | Bedrock AgentCore Runtime (MicroVMs) | Agent sessions (default) | Yes |
 | ECS Fargate (when enabled) | Agent sessions (opt-in) | Yes |
-| Lambda (Node.js 24, ARM64) | Orchestrator, API handlers, reconciler, custom resources | Yes |
+| Lambda (Node.js 24, ARM64) | Orchestrator, API handlers, fanout consumer, reconcilers, custom resources | Yes |
 
 ### AI/ML
 
@@ -88,8 +88,10 @@ For the full cost model including per-task costs, see [COST_MODEL.md](/architect
 
 | Service | Used By | Scales to Zero |
 |---------|---------|---------------|
-| DynamoDB (5 tables, PAY_PER_REQUEST) | Task state, events, concurrency, webhooks, repo config | Yes |
-| S3 | CDK asset bucket, ECR image layers, FUSE session storage | Minimal |
+| DynamoDB (6 tables, PAY_PER_REQUEST) | Task state, events, nudges, concurrency, webhooks, repo config | Yes |
+| DynamoDB Streams | TaskEventsTable → FanOut Consumer Lambda | Yes |
+| S3 | CDK asset bucket, ECR image layers, FUSE session storage, trace artifacts (7-day lifecycle) | Minimal |
+| SQS (DLQ) | FanOut Consumer dead-letter queue | Yes |
 | Secrets Manager | GitHub PAT, webhook HMAC secrets | **No** (~$0.40/secret/mo) |
 
 ### API / Auth
@@ -100,6 +102,12 @@ For the full cost model including per-task costs, see [COST_MODEL.md](/architect
 | Cognito User Pool | CLI/API authentication | Yes (free tier) |
 | WAF v2 | API Gateway protection (managed rules + rate limiting) | **No** (~$5/mo base) |
 
+### Scheduling
+
+| Service | Used By | Scales to Zero |
+|---------|---------|---------------|
+| EventBridge (scheduled rule) | Stranded task reconciler (every 5 min) | Yes (rule is free; Lambda invocation is the cost) |
+
 ### Observability
 
 | Service | Used By | Scales to Zero |
