Feature: Code execution Middleware

[saharannaveen]

Description

What does this MR do and why?

Implements CodeExecutionMiddleware — a deepagents AgentMiddleware that injects an execute_code tool into the agent and
routes calls to ephemeral K8s Jobs for sandboxed code execution. Agents can now generate Python/shell/Node code, execute it
in an isolated container, and receive stdout/stderr back — with full observability, security enforcement, and automatic
cleanup.

Changes

Core middleware (deep_agent/src/code_execution/middleware.py): CodeExecutionMiddleware(AgentMiddleware) injects execute_code
tool via awrap_model_call, intercepts calls in awrap_tool_call, validates input (language, code length, empty code, file
size), manages per-org concurrency via asyncio.Semaphore, routes to K8sJobRunner, and returns structured ToolMessage with
stdout/stderr/exit_code.

K8s Job runner (deep_agent/src/code_execution/k8s_job_runner.py): Manages the full ephemeral Job lifecycle — manifest
generation with full pod security context (non-root, read-only FS, no SA token, seccomp, drop all caps), pod polling, log
collection (post-completion + streaming via follow=True), container status parsing (success/failed/timeout/OOM), cost
tracking via K8s Metrics API, NetworkPolicy creation/deletion per execution, ConfigMap-based file I/O, and cleanup in
finally block.

Configuration (deep_agent/src/code_execution/config.py): Pydantic model with configurable images, resource limits, timeout
(5-300s, default 60s), network access control (deny/allow_internet/per_execution), execution queuing (max concurrent per
org, queue timeout), cost tracking, streaming, and file I/O limits.

Observability (deep_agent/src/code_execution/metrics.py): 4-layer observability using stdlib logging (to ensure output
inside LangGraph graph-execution context): structured JSON logs for all lifecycle events, OTEL metric recording, OTEL
tracing spans, and platform audit event emission.

Wiring (deep_agent/src/infrastructure/middleware.py, deep_agent/src/agent/config/middleware.py): Registered in
build_middleware_list() following the existing middleware builder pattern. Config loaded from code_execution: section in
agent.yaml.

SSE streaming: Middleware wires LangGraph StreamWriter callback to K8sJobRunner.on_output for real-time code output
streaming through Aegra → BFF → UI.

Prompt updates (config/agent/PROMPT.md): Added code execution guidance — agent uses execute_code automatically for
computation tasks, with fallback for BMI when analyst subagent is unavailable.

Design spec with Mermaid diagrams covering architecture, before/after, platform integration, request flow, security constraints, K8s Job spec, observability design (4 layers), error handling taxonomy, alternatives analysis, imageconfiguration flow, and ephemeral pod observability guide.

AI Disclosure

AI used: Yes
Tool(s): None
Scope: Full implementation — design spec, middleware, K8s runner, config, metrics, tests, prompt engineering, bug fixes from code review
Human verification: Tested end-to-end on Kind cluster — Python/shell execution, file I/O via ConfigMap, NetworkPolicy
creation/deletion, execution queuing, cost tracking metrics, log streaming. 59 unit tests passing. All pre-commit hooks
green (ruff, mypy, pydocstyle, bandit).

Checklist

• I have reviewed my own diff
• Tests pass with adequate coverage (59 unit tests)
• Docs and config updated (1,854-line design spec, agent.yaml, PROMPT.md)
• AI output verified for correctness and hallucinated dependencies

Deployment & Security Impact

Deployment: Code execution enabled by default (code_execution.enabled: true). Requires kubernetes Python package (imported lazily — no crash if missing, just runtime error on first execute_code call). Agent pod ServiceAccount needs RBAC Role for batch/jobs (create/get/delete), pods (get/list), pods/log (get), networking.k8s.io/networkpolicies (create/delete) in its namespace. No DB migrations.

Security: Execution pods run with runAsNonRoot, readOnlyRootFilesystem, automountServiceAccountToken: false,
capabilities.drop: [ALL], seccompProfile: RuntimeDefault. NetworkPolicy created per execution to control egress. Code
content never logged — only SHA-256 hash in audit events. Resource limits enforced via K8s resources.limits. Timeout
enforced via activeDeadlineSeconds + client-side asyncio.wait_for.

Reviewer Notes

Focus on:

• k8s_job_runner.py lines 225-340 — the run() method orchestrating the full lifecycle. Verify ConfigMap/NetworkPolicy
  created inside try block and cleaned up in finally.
• middleware.py lines 140-260 — semaphore acquire/release flow. Verify acquired flag prevents over-release on timeout.
• k8s_job_runner.py line 595 — egress=egress (was egress if egress else None which treated [] as falsy → allowed all egress
  in deny mode).
• middleware.py lines 176-185 — StreamWriter callback. Verify graceful degradation when get_stream_writer() not available.