[AAASM-2288] ✨ (scenarios/sidecar-runtime): Add sidecar-runtime scenario with Docker Compose and agent examples

[Chisanan232]

What changed

Added scenarios/sidecar-runtime/ demonstrating how to run agent examples against a local Agent Assembly runtime via Docker Compose. Includes:

• README.md — concept diagram, setup/run/cleanup commands, port/env-var table, troubleshooting
• docker-compose.yml — assembly-gateway service definition (mock or real gateway)
• mock-gateway/Dockerfile + mock-gateway/server.js — lightweight Node.js HTTP mock that evaluates tool calls against a simple policy
• scripts/start.sh — starts the runtime, waits for health check, prints instructions
• scripts/stop.sh — tears down containers cleanly
• examples/python-agent/agent.py — Python agent that connects to gateway or falls back to offline policy
• examples/node-agent/agent.js — Node.js equivalent

Both agent examples run fully offline without Docker (offline mode), and connect to the real gateway container when ASSEMBLY_GATEWAY_URL is set.

Related ticket

Closes #AAASM-2288

How to verify

Offline (no Docker required):

python scenarios/sidecar-runtime/examples/python-agent/agent.py
node scenarios/sidecar-runtime/examples/node-agent/agent.js

With local runtime (Docker required):

cd scenarios/sidecar-runtime
bash scripts/start.sh
export ASSEMBLY_GATEWAY_URL=http://localhost:8080
python examples/python-agent/agent.py
node examples/node-agent/agent.js
bash scripts/stop.sh

Checklist

• PR title follows [AAASM-XXXX] <GitEmoji> (<scope>): <summary>
• No secrets, API keys, or .env files committed
• Example sub-projects include their own README.md with prerequisites and run instructions
• SDK/runtime version dependencies are documented or pinned

[sonarqubecloud]

Quality Gate failed

Failed conditions
2 Security Hotspots
C Security Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[Chisanan232]

Code Review — Claude Code

Scope review result: ✅ Ready to merge

CI status

Check	Result
build	✅ pass
run	✅ pass
SonarCloud	⚠️ fail (quality gate — ignored per project policy)

Coverage against AAASM-2288 / AAASM-2197 AC-3

Requirement	Status
scenarios/sidecar-runtime/README.md — concept diagram, ports table, setup/run/cleanup, troubleshooting, production notes	✅ present
docker-compose.yml — defines assembly-gateway service with health check	✅ present
scripts/start.sh — starts runtime, waits for health check, prints instructions	✅ present
scripts/stop.sh — tears down containers cleanly	✅ present
examples/python-agent/agent.py — connects to gateway when ASSEMBLY_GATEWAY_URL is set	✅ present
examples/node-agent/agent.js — same pattern	✅ present
Offline fallback (no Docker required)	✅ both agents fall back to local policy when ASSEMBLY_GATEWAY_URL unset
Ports and environment variables documented	✅ README table: port 8080 HTTP, 50051 gRPC production, ASSEMBLY_GATEWAY_URL
No secrets / API keys committed	✅ .env.example only
mock-gateway/ ships a self-contained Dockerfile + Node.js HTTP server	✅ 55-line server.js — no external deps

Observations

• The mock-gateway/server.js correctly returns decision: deny for delete_file and drop_database, and allow for everything else — mirrors the real gateway's default-allow model.
• start.sh polls docker compose ps for healthy state before printing instructions — avoids race conditions where the container starts but the port isn't ready.
• Agents print an explicit "offline mode" banner when ASSEMBLY_GATEWAY_URL is unset, so developers know exactly what's happening.

No issues found. Approved from scope and correctness standpoint.