Merge staging into main

.gitignore

@@ -48,7 +48,11 @@ unity.egg-info/
 .tmux_logs/
 intranet/logs/
 *:Zone.Identifier
-assets/
+# assets/ holds local screenshots by default; allow-list specific repo-shipped
+# diagrams below. (Use 'assets/*' rather than 'assets/' so the exceptions take
+# effect — git can't un-ignore a file inside a fully-ignored directory.)
+assets/*
+!assets/hero-architecture.svg
 discord_messages.md
 .cursor/debug.log
 # ConversationManager sandbox persistent config (project-local)

scripts/setup.sh

@@ -145,14 +145,72 @@ ensure_orchestra_repo() {
     log_success "orchestra: $(git -C "$ORCHESTRA_REPO" rev-parse --short HEAD)"
 }
 
+# --- Python 3.12 selection for poetry --------------------------------------
+# Orchestra pins itself to ~3.12 because several core deps (asyncpg, tiktoken,
+# ...) ship no Python 3.13 wheels. Locate a 3.12 interpreter ourselves and
+# tell poetry to use it explicitly, so users on a 3.13-default system don't
+# get surprise build errors.
+find_python312() {
+    # 1. uv-managed Python (uv is required upstream by install.sh)
+    if command -v uv >/dev/null 2>&1; then
+        local uv_py
+        uv_py=$(uv python find 3.12 2>/dev/null || true)
+        if [ -n "$uv_py" ] && [ -x "$uv_py" ]; then
+            echo "$uv_py"
+            return 0
+        fi
+        log_info "Installing Python 3.12 via uv (orchestra requires it)..."
+        uv python install 3.12 >/dev/null 2>&1 || true
+        uv_py=$(uv python find 3.12 2>/dev/null || true)
+        if [ -n "$uv_py" ] && [ -x "$uv_py" ]; then
+            echo "$uv_py"
+            return 0
+        fi
+    fi
+    # 2. system python3.12 on PATH
+    if command -v python3.12 >/dev/null 2>&1; then
+        command -v python3.12
+        return 0
+    fi
+    return 1
+}
+
 install_orchestra_deps() {
     log_info "Installing orchestra dependencies via poetry (first-time: a few minutes)..."
-    (cd "$ORCHESTRA_REPO" && poetry install --no-interaction --quiet) || {
-        log_error "poetry install failed in $ORCHESTRA_REPO"
-        log_info "Try manually: cd $ORCHESTRA_REPO && poetry install"
+
+    local py312
+    py312="$(find_python312)" || {
+        log_error "Couldn't locate a Python 3.12 interpreter."
+        log_info "Orchestra requires Python 3.12.x. Install one with:"
+        log_info "  uv python install 3.12        (uv was installed by install.sh)"
+        log_info "  brew install python@3.12      (macOS via Homebrew)"
+        log_info "  sudo apt-get install python3.12 python3.12-venv   (Debian/Ubuntu)"
         return 1
     }
-    log_success "Orchestra dependencies installed"
+    log_info "Using Python 3.12 at $py312"
+
+    (cd "$ORCHESTRA_REPO" && poetry env use "$py312" >/dev/null 2>&1) || {
+        log_warn "Couldn't pin poetry env to $py312 — proceeding (may fail)."
+    }
+
+    # Capture install output so a failure surfaces the actual cause instead
+    # of an opaque "poetry install failed" message.
+    local install_log
+    install_log="$(mktemp)"
+    if (cd "$ORCHESTRA_REPO" && poetry install --no-interaction) >"$install_log" 2>&1; then
+        rm -f "$install_log"
+        log_success "Orchestra dependencies installed"
+    else
+        log_error "poetry install failed in $ORCHESTRA_REPO"
+        echo ""
+        echo "  --- Last 40 lines of poetry output ---"
+        tail -40 "$install_log" | sed 's/^/  /'
+        echo "  --------------------------------------"
+        echo "  Full log: $install_log"
+        echo ""
+        log_info "Try manually:  cd $ORCHESTRA_REPO && poetry install"
+        return 1
+    fi
 }
 
 # --- Orchestra spin-up ----------------------------------------------------

tests/actor/code_act/test_execute_function_bare_handle.py

@@ -12,7 +12,9 @@
 
 from __future__ import annotations
 
+import inspect
 from typing import Any, AsyncIterator
+from unittest.mock import AsyncMock
 
 import pytest
 import pytest_asyncio
@@ -21,6 +23,7 @@
 from unity.actor.execution import ExecutionResult
 from unity.actor.environments import StateManagerEnvironment
 from unity.common.async_tool_loop import SteerableToolHandle
+from unity.common.llm_helpers import method_to_schema
 from unity.function_manager.function_manager import FunctionManager
 from unity.function_manager.primitives import Primitives, PrimitiveScope
 from unity.manager_registry import ManagerRegistry
@@ -94,6 +97,113 @@ async def execute_function_tool(
 # ---------------------------------------------------------------------------
 
 
+class _FakeFunctionManager:
+    def __init__(self):
+        self.execute_in_venv = AsyncMock(
+            return_value={
+                "stdout": [],
+                "stderr": [],
+                "result": "venv ok",
+                "error": None,
+            },
+        )
+
+    def _get_function_data_by_name(self, *, name: str):
+        if name != "stored_report":
+            return None
+        return {
+            "function_id": 12,
+            "name": "stored_report",
+            "implementation": "def stored_report():\n    return 'default env'",
+            "venv_id": 31,
+            "is_primitive": False,
+        }
+
+    def search_functions(self, **kwargs):
+        return {"metadata": []}
+
+    def filter_functions(self, **kwargs):
+        return {"metadata": []}
+
+    def list_functions(self, **kwargs):
+        return {"metadata": []}
+
+    async def add_functions(self, **kwargs):
+        return {"metadata": []}
+
+    async def delete_function(self, **kwargs):
+        return {"deleted": True}
+
+
+@pytest.mark.asyncio
+async def test_execute_function_does_not_expose_venv_id():
+    fm = _FakeFunctionManager()
+    actor = CodeActActor(
+        function_manager=fm,  # type: ignore[arg-type]
+        can_store=False,
+    )
+
+    try:
+        execute_function = actor.get_tools("act")["execute_function"]
+        if hasattr(execute_function, "fn"):
+            execute_function = execute_function.fn
+
+        signature = inspect.signature(execute_function)
+        schema = method_to_schema(
+            execute_function,
+            tool_name="execute_function",
+            include_class_name=False,
+        )
+    finally:
+        await actor.close()
+
+    assert "venv_id" not in signature.parameters
+    assert "venv_id" not in schema["function"]["parameters"]["properties"]
+    assert "venv_id" not in schema["function"]["description"]
+
+
+@pytest.mark.asyncio
+async def test_execute_function_uses_stored_venv_when_caller_omits_it():
+    fm = _FakeFunctionManager()
+    actor = CodeActActor(
+        function_manager=fm,  # type: ignore[arg-type]
+        can_store=False,
+    )
+    captured: dict[str, object] = {}
+
+    async def _fake_execute(**kwargs):
+        captured.update(kwargs)
+        return {
+            "stdout": [],
+            "stderr": [],
+            "result": "venv ok",
+            "error": None,
+            "language": kwargs["language"],
+            "state_mode": kwargs["state_mode"],
+            "session_id": kwargs["session_id"],
+            "venv_id": kwargs["venv_id"],
+            "session_created": False,
+            "duration_ms": 0,
+        }
+
+    actor._session_executor.execute = AsyncMock(side_effect=_fake_execute)  # type: ignore[method-assign]
+
+    try:
+        execute_function = actor.get_tools("act")["execute_function"]
+        if hasattr(execute_function, "fn"):
+            execute_function = execute_function.fn
+
+        result = await execute_function(
+            function_name="stored_report",
+            call_kwargs={},
+        )
+    finally:
+        await actor.close()
+
+    assert result.result == "venv ok"
+    assert captured["venv_id"] == 31
+
+
 @pytest.mark.asyncio
 @pytest.mark.timeout(120)
 async def test_execute_function_returns_bare_handle_for_primitive(