Feature: Code execution Middleware

.env.example

@@ -1,38 +1,121 @@
-# Agent Server Configuration
-AGENT_HOST=0.0.0.0
-AGENT_PORT=5002
-#AGENT_SSL_KEYFILE=/path_to/ssl_key.pem
-#AGENT_SSL_CERTFILE=/path_to/ssl_cert.pem
+# ==============================================================================
+# Environment Variables
+#
+# Only secrets and infrastructure endpoints belong here.
+# All operational config (cache, middleware, filesystem, providers) lives in
+# config/agent/runtime/agent.yaml — the single source of truth.
+#
+# OpenShift: secrets come via Secrets, infra via ConfigMaps.
+# ==============================================================================
 
-# Python Logging
-PYTHON_LOG_LEVEL=INFO
+# --- Environment ---
+# Set to "production" to enforce security hardening:
+# - ENABLE_AUTH must be true
+# - MCP ssl_verify cannot be disabled
+# - PII is scrubbed from error responses
+# - Security headers are enforced
+ENVIRONMENT=development
+
+# --- Security ---
+# Request body size limit (bytes) - prevents DoS attacks
+REQUEST_BODY_MAX_SIZE=10485760  # 10MB
+
+# --- SSO / OIDC Authentication ---
+# Supports any OIDC-compliant provider (Keycloak, Okta, Azure AD, Auth0, etc.)
+ENABLE_AUTH=false
+SSO_ISSUER_URL=https://sso.example.com/realms/myrealm
+SSO_CLIENT_ID=your-client-id
+SSO_CLIENT_SECRET=your-client-secret
+# SSO_JWKS_URI=https://sso.example.com/realms/myrealm/protocol/openid-connect/certs
+
+# Dev fallback identity (used when ENABLE_AUTH=false)
+SSO_DEV_USERNAME=John Doe
+SSO_DEV_USER_ID=dev-user
+
+# User ID encryption for observability privacy
+ENABLE_USER_ID_ENCRYPTION=false
+# USER_ID_ENCRYPTION_KEY=your-32-byte-hex-key
 
-USE_INMEMORY_SAVER=true
+# MCP OAuth token encryption (Fernet key — required when using auth_mode oauth/dcr)
+# Encrypts access/refresh tokens in Redis and DCR client secrets in Postgres.
+# Generate: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+# MCP_TOKEN_ENCRYPTION_KEY=
+# Optional previous key during rotation (decrypt only — see README)
+# MCP_TOKEN_ENCRYPTION_KEY_PREVIOUS=
+# AGENT_PUBLIC_BASE_URL=http://localhost:5002
 
-# pgvector credentials for agentic memory (used when USE_INMEMORY_SAVER=false)
-POSTGRES_USER=pgvector
-POSTGRES_PASSWORD=pgvector
-POSTGRES_HOST=0.0.0.0
+# --- Infrastructure ---
+
+# Postgres (checkpoints, memory, feedback)
+# Local dev (`make local`): localhost + port published by compose pgvector (5432)
+POSTGRES_HOST=localhost
 POSTGRES_PORT=5432
-POSTGRES_DB=pgvector
+POSTGRES_DB=template_agent
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+
+# Redis (Aegra broker: SSE streaming, job queue, crash recovery)
+# Local dev (`make local`): localhost + port published by compose redis (6379)
+REDIS_URL=redis://localhost:6379/0
+REDIS_BROKER_ENABLED=true
+
+# MongoDB (platform token usage rollup — optional, set by deploy components)
+#
+# SECURITY: MONGODB_URI may contain credentials in the URI itself:
+#   mongodb://user:password@host:27017/tokenusage?authSource=tokenusage
+#
+# - NEVER commit a URI with credentials to version control.
+# - NEVER log or expose this value in error messages or debug output.
+# - In production, inject via secrets management:
+#     Kubernetes : mount as a Secret, reference via envFrom or env.valueFrom.secretKeyRef
+#     AWS        : use Secrets Manager or SSM Parameter Store with an operator/init container
+#     GCP        : use Secret Manager with Workload Identity
+#     Vault      : use the Vault Agent injector or ESO (External Secrets Operator)
+# - Scope the MongoDB user to read/write on the tokenusage DB only — no admin privileges.
+# - Rotate credentials without redeploying by updating the secret and triggering a rollout.
+#
+# Local dev (unauthenticated, never in production):
+# MONGODB_URI=mongodb://localhost:27017
+# MONGODB_DB=tokenusage
+
+# --- Observability ---
 
-# exception
-LANGFUSE_SECRET_KEY=sk-lf-f46b492e-9335-
-LANGFUSE_PUBLIC_KEY=pk-lf-dfa0dab0-c486-
+# Langfuse (v4 SDK — auto-read by client and CallbackHandler)
+LANGFUSE_PUBLIC_KEY=pk-lf-...
+LANGFUSE_SECRET_KEY=sk-lf-...
 LANGFUSE_BASE_URL=https://cloud.langfuse.com
 LANGFUSE_TRACING_ENVIRONMENT=development
 
-#Google Vertex AI service creds
+# OpenTelemetry — token budget export (metrics/traces via otel_setup.py)
+# Agent lifecycle metrics (conversations, streams, threads) via observability.yaml
+# ENABLE_OTEL_METRICS=false
+# OTEL_EXPORTER_OTLP_ENDPOINT=
+# ENABLE_OTEL_TRACES=false
+# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4317
+# OTEL_SERVICE_NAME=template-agent
+# OTEL_AUTH_TOKEN=
+# OTEL_METRIC_EXPORT_INTERVAL_MILLIS=10000
+# ENABLE_OTEL=false
+# OTEL_EXPORTER_OTLP_INSECURE=true
+# OTEL_METRIC_EXPORT_INTERVAL=5000
+
+# --- Model Provider Credentials ---
+
+# Google Vertex AI
 GOOGLE_APPLICATION_CREDENTIALS_CONTENT='{
     "type": "service_account",
-    "project_id": "data-and-ai-gemini",
-    ...
-    ...
+    "project_id": "your-project-id",
     ...
     "universe_domain": "googleapis.com"
   }'
 
-# MCP config
-MCP_SERVER_NAME=template-mcp-server
-MCP_SERVER_URL=http://localhost:5001/mcp
-MCP_TRANSPORT_PROTOCOL=streamable_http
+# vLLM / OpenAI-compatible (optional)
+# VLLM_BASE_URL=http://vllm-server:8000/v1
+# VLLM_API_KEY=EMPTY
+
+# --- Runtime (rarely changed) ---
+
+PYTHON_LOG_LEVEL=INFO
+
+# Per-MCP OAuth client secret (auth_mode: oauth — referenced via oauth.client_secret_env in mcp.json)
+# MY_OAUTH_MCP_CLIENT_SECRET=your-client-secret

.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+
+  - package-ecosystem: docker
+    directory: "/"
+    schedule:
+      interval: weekly
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

.github/workflows/build-base-image.yml

@@ -0,0 +1,180 @@
+name: Build and Push Base Image
+
+on:
+  push:
+    tags:
+      - '*'
+    branches:
+      # - main
+      - deep-agent
+  workflow_dispatch:  # Allow manual trigger for testing
+
+permissions:
+  contents: write
+  packages: write
+  security-events: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels)
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=ref,event=tag
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=sha,prefix={{branch}}-,enable=${{ !startsWith(github.ref, 'refs/tags/') }}
+
+      - name: Extract version for deployment package
+        id: version
+        run: |
+          if [[ "${{ github.ref }}" == refs/tags/* ]]; then
+            VERSION="${GITHUB_REF#refs/tags/}"
+          else
+            VERSION="${GITHUB_REF#refs/heads/}-${GITHUB_SHA::7}"
+          fi
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+          echo "package_name=agent-deployment.zip" >> $GITHUB_OUTPUT
+
+      - name: Build image locally for scanning
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Containerfile
+          push: false
+          load: true
+          tags: scan-target:${{ steps.version.outputs.version }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          platforms: linux/amd64
+
+      - name: Scan image for vulnerabilities
+        uses: aquasecurity/trivy-action@v0.36.0
+        with:
+          image-ref: scan-target:${{ steps.version.outputs.version }}
+          format: table
+          severity: CRITICAL,HIGH
+          scanners: vuln
+          trivyignores: .trivyignore
+          exit-code: '1'
+
+      - name: Generate SARIF report
+        uses: aquasecurity/trivy-action@v0.36.0
+        if: always()
+        with:
+          image-ref: scan-target:${{ steps.version.outputs.version }}
+          format: sarif
+          output: trivy-results.sarif
+          scanners: vuln
+          exit-code: '0'
+
+      - name: Upload Trivy scan results to GitHub Security tab
+        if: always() && hashFiles('trivy-results.sarif') != ''
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: trivy-results.sarif
+
+      - name: Upload Trivy report as artifact
+        if: always() && hashFiles('trivy-results.sarif') != ''
+        uses: actions/upload-artifact@v4
+        with:
+          name: trivy-report-${{ steps.version.outputs.version }}
+          path: trivy-results.sarif
+          retention-days: 30
+
+      - name: Push multi-platform image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Containerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          platforms: linux/amd64,linux/arm64
+
+      - name: Create deployment package metadata
+        run: |
+          cat > deployment/release-info.json <<EOF
+          {
+            "version": "${{ steps.version.outputs.version }}",
+            "git_ref": "${{ github.ref }}",
+            "git_sha": "${{ github.sha }}",
+            "build_date": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+            "container_image": "ghcr.io/${{ github.repository }}:${{ steps.version.outputs.version }}",
+            "repository": "${{ github.repository }}"
+          }
+          EOF
+          cat deployment/release-info.json
+
+      - name: Create deployment package
+        run: |
+          cd deployment
+          zip -r ../${{ steps.version.outputs.package_name }} . -x "*.git*"
+          cd ..
+          echo "Created package: ${{ steps.version.outputs.package_name }}"
+          ls -lh ${{ steps.version.outputs.package_name }}
+
+      - name: Create GitHub Release (for tags only)
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v1
+        with:
+          files: ${{ steps.version.outputs.package_name }}
+          generate_release_notes: true
+          draft: false
+          prerelease: ${{ contains(github.ref, 'alpha') || contains(github.ref, 'beta') || contains(github.ref, 'rc') }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload deployment package as artifact (for branch builds)
+        if: "!startsWith(github.ref, 'refs/tags/')"
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ steps.version.outputs.package_name }}
+          path: ${{ steps.version.outputs.package_name }}
+          retention-days: 30
+
+      - name: Build summary
+        run: |
+          echo "### Base Image Built Successfully! 🚀" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Version:** \`${{ steps.version.outputs.version }}\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Container Image Tags:**" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          echo "${{ steps.meta.outputs.tags }}" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Pull command:**" >> $GITHUB_STEP_SUMMARY
+          echo '```bash' >> $GITHUB_STEP_SUMMARY
+          echo "docker pull ghcr.io/${{ github.repository }}:${{ steps.version.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Deployment Package:**" >> $GITHUB_STEP_SUMMARY
+          if [[ "${{ github.ref }}" == refs/tags/* ]]; then
+            echo "📦 \`${{ steps.version.outputs.package_name }}\` attached to release" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "📦 \`${{ steps.version.outputs.package_name }}\` uploaded as workflow artifact" >> $GITHUB_STEP_SUMMARY
+          fi