feat(agents): add Jupyter-backed code policy module

[TomCC7]

Contribution path

• Small, safe change that does not need a tracking issue
• Stacked on feat(cli): add interactive RPC shell #3236

Problem

DimOS agents can call predefined skills, but they cannot submit a Python program that processes native observations, branches or retries, and composes deployed RPCs as one synchronous policy rollout.

Solution

• Add a persistent CodePolicyModule exposing one synchronous python_exec(code, timeout_s) MCP skill.
• Use the standard jupyter_client + ipykernel stack instead of a custom worker protocol.
• Lazily bootstrap the parent PR's connected Dimos app handle and a Memory2 SqliteStore attached to the explicitly configured recorder database.
• Preserve the Jupyter namespace across calls and ordinary Python errors.
• On timeout, interrupt first and preserve the namespace when the kernel recovers; restart only an unresponsive or dead kernel.
• Record raw and derived manipulation observations at a stable database path without changing Memory2 core, then enable the interface only in xarm-perception-sim-agent.
• Add soft prompt guidance that prefers code execution for observation processing and multi-RPC control flow while retaining direct skills for atomic actions.
• Use standard DimOS structured logs and Jupyter execution identity for submitted source, output, duration, timeouts, interrupts, and restarts.

ipykernel and jupyter-client are explicit dependencies of the agents extra and are imported lazily. The v1 interface is foreground-only, text-only, single-call-at-a-time, and intentionally not a security sandbox. Real-hardware blueprints are unchanged.

How to Test

Install and run the xArm simulation:

uv sync --extra agents --extra manipulation
uv run dimos --simulation --viewer none run xarm-perception-sim-agent \
  -o pickandplacemodule.visualization.backend=none

From another terminal:

uv run dimos mcp call python_exec --json-args \
  '{"code":"print(memory.list_streams()); print(app.skills.get_robot_state())"}'

Focused automated validation:

uv run pytest \
  dimos/agents/test_code_policy.py \
  dimos/codebase_checks/test_no_init_files.py \
  dimos/codebase_checks/test_no_all.py \
  dimos/memory2/test_module.py \
  dimos/memory2/test_registry.py \
  dimos/memory2/test_store.py \
  dimos/perception/test_manipulation_policy_recorder.py \
  dimos/perception/detection/type/detection3d/test_object_aggregation.py \
  dimos/robot/manipulators/xarm/blueprints/test_agentic.py

The focused suite passes 129 tests. Ruff formatting/checks, strict mypy over the changed source files, blueprint registry generation, lockfile validation, staged pre-commit hooks, and git diff --check also pass. A live MCP smoke test verified access to an actively recording Memory2 database, DimOS RPC calls, namespace persistence, historical queries, and interrupt-first timeout recovery.

AI assistance

OpenAI Codex with GPT-5 was substantially involved in design discussion, implementation, tests, documentation, and validation. The author reviewed and approved the direction interactively.

Checklist

• I have read and approved the CLA.

[codecov]

Codecov Report

❌ Patch coverage is 89.44724% with 42 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
dimos/agents/code_policy.py	80.88%	31 Missing and 8 partials ⚠️
...os/perception/detection/type/detection3d/object.py	33.33%	2 Missing ⚠️
dimos/perception/worldbelief_recorder.py	50.00%	0 Missing and 1 partial ⚠️

@@                   Coverage Diff                   @@
##           cc/feat/repl-module    #3259      +/-   ##
=======================================================
+ Coverage                75.01%   75.09%   +0.08%     
=======================================================
  Files                     1118     1124       +6     
  Lines                   106527   106923     +396     
  Branches                  9690     9711      +21     
=======================================================
+ Hits                     79910    80298     +388     
+ Misses                   23796    23793       -3     
- Partials                  2821     2832      +11     

Flag	Coverage Δ
OS-ubuntu-24.04-arm	68.94% <89.44%> (+0.29%)	⬆️
OS-ubuntu-latest	70.79% <89.44%> (+0.13%)	⬆️
Py-3.10	70.78% <89.44%> (+0.13%)	⬆️
Py-3.11	70.79% <89.44%> (+0.14%)	⬆️
Py-3.12	70.78% <89.44%> (+0.14%)	⬆️
Py-3.13	70.78% <89.44%> (+0.13%)	⬆️
Py-3.14	70.79% <89.44%> (+0.14%)	⬆️
Py-3.14t	70.79% <89.44%> (+0.14%)	⬆️
SelfHosted-macOS	34.99% <29.89%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
dimos/agents/test_code_policy.py	100.00% <100.00%> (ø)
...ection/type/detection3d/test_object_aggregation.py	100.00% <100.00%> (ø)
dimos/perception/manipulation_policy_recorder.py	100.00% <100.00%> (ø)
...os/perception/test_manipulation_policy_recorder.py	100.00% <100.00%> (ø)
dimos/robot/all_blueprints.py	100.00% <ø> (ø)
dimos/robot/manipulators/common/agent_prompts.py	100.00% <100.00%> (ø)
...imos/robot/manipulators/xarm/blueprints/agentic.py	100.00% <100.00%> (ø)
...robot/manipulators/xarm/blueprints/test_agentic.py	100.00% <100.00%> (ø)
dimos/perception/worldbelief_recorder.py	75.00% <50.00%> (+9.54%)	⬆️
...os/perception/detection/type/detection3d/object.py	29.62% <33.33%> (+1.82%)	⬆️
... and 1 more

... and 6 files with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[leshy]

what is this file? this whole file needs to be deleted

[leshy]

I think this belongs closer to your blueprints and not in detections or perception