feat(interactive-agents): async-only background task UX + Cedar HITL design

AGENTS.md

@@ -20,6 +20,7 @@ Use this routing before editing so the right package and tests get updated:
 | Shared API request/response shapes | `cdk/src/handlers/shared/types.ts` | **`cli/src/types.ts`** (must stay in sync) |
 | `bgagent` CLI commands and HTTP client | `cli/src/`, `cli/test/` | `cli/src/types.ts` if API types change |
 | Agent runtime (clone, tools, prompts, container) | `agent/src/` (`pipeline.py`, `runner.py`, `config.py`, `hooks.py`, `policy.py`, `prompts/`, Dockerfile, etc.) | `agent/tests/`, `agent/README.md` for env/PAT |
+| Agent progress events (written to `TaskEventsTable` from the MicroVM; read by `bgagent watch`) | `agent/src/progress_writer.py`, `agent/src/pipeline.py` and `agent/src/runner.py` (integration points) | `agent/tests/test_progress_writer.py`; `cli/src/commands/watch.ts` for the consumer side |
 | User-facing or design prose | `docs/guides/`, `docs/design/` | Run **`mise //docs:sync`** or **`mise //docs:build`** (do not edit `docs/src/content/docs/` by hand) |
 | Monorepo tasks, CI glue | Root `mise.toml`, `scripts/`, `.github/workflows/` | — |
 

agent/README.md

@@ -98,6 +98,7 @@ The `run.sh` script overrides the container's default CMD to run `python /app/sr
 | `MAX_BUDGET_USD` | No | | **Local batch only** (shell env when running `entrypoint.py` directly). Range 0.01–100; agent stops when the budget is reached. For deployed AgentCore **server** mode and production tasks, set **`max_budget_usd`** on task creation (REST API, CLI `--max-budget`, or Blueprint default); the orchestrator sends it in the `/invocations` JSON body — server mode does not read `MAX_BUDGET_USD` from the environment. |
 | `DRY_RUN` | No | | Set to `1` to validate config and print the prompt without running the agent |
 | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | No | `anthropic.claude-haiku-4-5-20251001-v1:0` | Bedrock model ID for the pre-flight safety check (see below) |
+| `NUDGES_TABLE_NAME` | No | | **Phase 2.** DynamoDB table for mid-task user nudges (`<user_nudge>` XML blocks injected between turns). If unset, the agent runs without nudge support — `nudge_reader.read_pending()` returns `[]` and logs a WARN once. Set automatically by the CDK stack on both AgentCore runtimes. |
 
 **Pre-flight check model**: Claude Code runs a quick safety verification using a small Haiku model before executing each tool command. On Bedrock, the default Haiku model ID may not be enabled in your account, causing the check to time out with *"Pre-flight check is taking longer than expected"* warnings. The agent sets `ANTHROPIC_DEFAULT_HAIKU_MODEL` to a known-available Bedrock Haiku model ID to avoid this. If you see pre-flight timeout warnings, verify that this model is enabled in your Bedrock model access settings.
 

agent/docker-compose.yml

@@ -0,0 +1,24 @@
+# Local development services for agent testing.
+#
+# Usage:
+#   docker compose up -d          # Start DynamoDB Local
+#   docker compose down            # Stop and clean up
+#
+# The agent container (run via run.sh --local-events) connects to
+# the "agent-local" network to reach DynamoDB Local at
+# http://dynamodb-local:8000.
+
+services:
+  dynamodb-local:
+    image: amazon/dynamodb-local:latest
+    container_name: dynamodb-local
+    ports:
+      - "8000:8000"
+    command: ["-jar", "DynamoDBLocal.jar", "-inMemory", "-sharedDb"]
+    networks:
+      - agent-local
+
+networks:
+  agent-local:
+    name: agent-local
+    driver: bridge

agent/mise.toml

@@ -72,3 +72,38 @@ run = [
     { task = "security:bandit" },
     { task = "security:image" },
 ]
+
+# LOCAL DEVELOPMENT (DynamoDB Local for progress events)
+
+[tasks."local:up"]
+description = "Start DynamoDB Local and create tables for local agent testing"
+run = [
+  "docker compose up -d",
+  "bash scripts/create-local-tables.sh",
+]
+
+[tasks."local:down"]
+description = "Stop DynamoDB Local (all data is ephemeral)"
+run = "docker compose down"
+
+[tasks."local:events"]
+description = "Query progress events from DynamoDB Local"
+run = """
+aws dynamodb scan \
+  --table-name TaskEventsTable \
+  --endpoint-url http://localhost:8000 \
+  --region us-east-1 \
+  --no-cli-pager \
+  --output table 2>/dev/null || echo "No events found (is DynamoDB Local running?)"
+"""
+
+[tasks."local:events:json"]
+description = "Query progress events from DynamoDB Local (JSON)"
+run = """
+aws dynamodb scan \
+  --table-name TaskEventsTable \
+  --endpoint-url http://localhost:8000 \
+  --region us-east-1 \
+  --no-cli-pager \
+  --output json 2>/dev/null || echo "{}"
+"""

agent/run.sh

@@ -8,12 +8,16 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 # ---------------------------------------------------------------------------
 usage() {
     cat <<'EOF'
-Usage: ./agent/run.sh [--server] <owner/repo> [args...]
+Usage: ./agent/run.sh [--server] [--local-events] <owner/repo> [args...]
 
 Modes:
   (default)   Local batch mode — runs the agent, then exits
   --server    Server mode — starts FastAPI on port 8080 (/invocations + /ping)
 
+Flags:
+  --local-events  Connect to DynamoDB Local (port 8000) for progress events.
+                  Requires: docker compose up -d && ./agent/scripts/create-local-tables.sh
+
 The second argument (after flags) is auto-detected:
   - If numeric, treated as a GitHub issue number
   - Otherwise, treated as a task description
@@ -47,6 +51,9 @@ Examples:
   # Local mode — dry run (print prompt, don't invoke agent)
   DRY_RUN=1 ./agent/run.sh "myorg/myrepo" 42
 
+  # Local mode with progress events to DynamoDB Local
+  ./agent/run.sh --local-events "myorg/myrepo" 42
+
   # Server mode — start FastAPI, then invoke via curl
   ./agent/run.sh --server "myorg/myrepo"
   curl http://localhost:8080/ping
@@ -61,13 +68,18 @@ EOF
 # Parse flags
 # ---------------------------------------------------------------------------
 MODE="local"
+LOCAL_EVENTS=false
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
         --server)
             MODE="server"
             shift
             ;;
+        --local-events)
+            LOCAL_EVENTS=true
+            shift
+            ;;
         --help|-h)
             usage
             ;;
@@ -206,6 +218,24 @@ DOCKER_ARGS=(
 [[ -n "${MAX_TURNS:-}" ]] && DOCKER_ARGS+=(-e "MAX_TURNS=${MAX_TURNS}")
 [[ -n "${MAX_BUDGET_USD:-}" ]] && DOCKER_ARGS+=(-e "MAX_BUDGET_USD=${MAX_BUDGET_USD}")
 
+# Local events mode: connect to DynamoDB Local via the agent-local network
+if [[ "$LOCAL_EVENTS" == true ]]; then
+    # Verify DynamoDB Local is running
+    if ! docker inspect dynamodb-local >/dev/null 2>&1; then
+        echo "ERROR: DynamoDB Local is not running." >&2
+        echo "  Start it with: cd agent && docker compose up -d" >&2
+        echo "  Create tables: ./agent/scripts/create-local-tables.sh" >&2
+        exit 1
+    fi
+    DOCKER_ARGS+=(
+        --network agent-local
+        -e "TASK_EVENTS_TABLE_NAME=TaskEventsTable"
+        -e "TASK_TABLE_NAME=TaskTable"
+        -e "AWS_ENDPOINT_URL_DYNAMODB=http://dynamodb-local:8000"
+    )
+    echo "  Events:    DynamoDB Local (http://localhost:8000)"
+fi
+
 # Server mode: expose port 8080
 if [[ "$MODE" == "server" ]]; then
     DOCKER_ARGS+=(-p 8080:8080)
@@ -236,6 +266,9 @@ echo "Monitor in another terminal:"
 echo "  docker logs -f ${CONTAINER_NAME}        # live output"
 echo "  docker stats ${CONTAINER_NAME}          # CPU, memory, disk I/O"
 echo "  docker exec ${CONTAINER_NAME} du -sh /workspace  # disk usage"
+if [[ "$LOCAL_EVENTS" == true ]]; then
+echo "  mise run local:events                   # query progress events"
+fi
 echo ""
 
 if [[ "$MODE" == "server" ]]; then

agent/scripts/create-local-tables.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# Create DynamoDB tables in DynamoDB Local for local agent testing.
+#
+# Prerequisites:
+#   docker compose up -d   (starts DynamoDB Local on port 8000)
+#   AWS CLI installed
+#
+# Usage:
+#   ./agent/scripts/create-local-tables.sh
+
+set -euo pipefail
+
+ENDPOINT="http://localhost:8000"
+REGION="us-east-1"
+
+# Common args for all commands
+DDB_ARGS=(--endpoint-url "$ENDPOINT" --region "$REGION" --no-cli-pager)
+
+echo "Creating local DynamoDB tables..."
+
+# ---------------------------------------------------------------------------
+# TaskEventsTable — matches cdk/src/constructs/task-events-table.ts
+#   PK: task_id (S), SK: event_id (S, ULID)
+#   TTL: ttl
+# ---------------------------------------------------------------------------
+if aws dynamodb describe-table --table-name TaskEventsTable "${DDB_ARGS[@]}" >/dev/null 2>&1; then
+  echo "  TaskEventsTable already exists — skipping"
+else
+  aws dynamodb create-table \
+    --table-name TaskEventsTable \
+    --attribute-definitions \
+      AttributeName=task_id,AttributeType=S \
+      AttributeName=event_id,AttributeType=S \
+    --key-schema \
+      AttributeName=task_id,KeyType=HASH \
+      AttributeName=event_id,KeyType=RANGE \
+    --billing-mode PAY_PER_REQUEST \
+    "${DDB_ARGS[@]}" >/dev/null
+  echo "  TaskEventsTable created"
+fi
+
+# ---------------------------------------------------------------------------
+# TaskTable — matches cdk/src/constructs/task-table.ts
+#   PK: task_id (S)
+#   TTL: ttl
+#   GSIs omitted (not needed for local agent testing)
+# ---------------------------------------------------------------------------
+if aws dynamodb describe-table --table-name TaskTable "${DDB_ARGS[@]}" >/dev/null 2>&1; then
+  echo "  TaskTable already exists — skipping"
+else
+  aws dynamodb create-table \
+    --table-name TaskTable \
+    --attribute-definitions \
+      AttributeName=task_id,AttributeType=S \
+    --key-schema \
+      AttributeName=task_id,KeyType=HASH \
+    --billing-mode PAY_PER_REQUEST \
+    "${DDB_ARGS[@]}" >/dev/null
+  echo "  TaskTable created"
+fi
+
+echo "Done. Tables available at $ENDPOINT"

agent/src/config.py

@@ -52,6 +52,8 @@ def build_config(
     task_type: str = "new_task",
     branch_name: str = "",
     pr_number: str = "",
+    trace: bool = False,
+    user_id: str = "",
 ) -> TaskConfig:
     """Build and validate configuration from explicit parameters.
 
@@ -102,6 +104,8 @@ def build_config(
         branch_name=branch_name,
         pr_number=pr_number,
         task_id=task_id or uuid.uuid4().hex[:12],
+        trace=trace,
+        user_id=user_id,
     )
 
 
@@ -118,6 +122,14 @@ def get_config() -> TaskConfig:
             max_budget_usd=float(os.environ.get("MAX_BUDGET_USD", "0")) or None,
             aws_region=os.environ.get("AWS_REGION", ""),
             dry_run=os.environ.get("DRY_RUN", "").lower() in ("1", "true", "yes"),
+            # Local-batch ``--trace`` parity (design §10.1). Without
+            # these env vars a developer running the agent outside
+            # AgentCore could never exercise the trace path. Both are
+            # opt-in; empty ``USER_ID`` with ``TRACE=1`` logs a skip
+            # warning (see ``pipeline.run_task``) rather than writing
+            # an unreachable ``traces//`` key.
+            trace=os.environ.get("TRACE", "").lower() in ("1", "true", "yes"),
+            user_id=os.environ.get("USER_ID", ""),
         )
     except ValueError as e:
         print(f"ERROR: {e}", file=sys.stderr)