Feature/openhands (#316)

* WebSettings

* WebChanges

* Add openhands sandbox tool

* feat: implement tool activity plugin to stream nested sub-agent tool calls to the web UI

* feat: implement usage metrics tracking with session-level cost reporting and planner configuration controls

* docs: add tool gating documentation and comprehensive usage/cost metrics guide, and update task tracker logic to enforce linear execution order and dependency resolution.

* feat: implement AgentOutputPlugin to surface delegated agent answers in chat and refine task tracker visibility rules

* refactor: serialize hypothesis verification by adding status-based queuing and a postponed backlog mechanism to prevent parallel execution.

* refactor: add optional roster support to critic prompts and change downloads page

* test: exclude HITL tools from prompt validation and update orchestrator-specific instruction checks

* feat: integrate CoderSandbox UI with dynamic status updates and update default root agent to PlanningPipelineAgent

* feat: enable configurable parallel hypothesis verification via new maxActiveHypotheses setting

* feat: add orchestrator_planner mode to allow OrchestratorAgent to use planning tools directly without PlannerAgent

* feat(web): add LiteLLM selective proxy, session import/export, and configurable coder modes
- Implemented LiteLLMProxy in `CoScientist/utils/selective_proxy.py` to route LLM and MCP traffic through forward proxy without closing shared httpx client sessions.
- Added session export and import functionality (`.cossession.zip`) in `CoScientist/web/session_bundle.py` with snapshot management.
- Refactored `coder_local_tools_enabled` to `coder_mode` ("local" | "openhands") across settings, assembly bindings, and unit tests.
- Updated Orchestrator prompt instructions to enforce sequential CoderAgent execution and avoid full source file dumps.
- Made HITL auto-approve timeout configurable (`hitl_auto_approve_timeout`).

* Merge remote-tracking branch 'origin/main' into feature/openhands

* feat: implement SequentialAgent pipeline for research lifecycle and rename Context Init to Research Frame.

* drop duplicate

* refactor: replace CONTEXT_INIT__ENABLED with RESEARCH_FRAME environment variable for configuration management

* refactor: standardize ADK agent tracing by caching run_root and updating Opik integration configuration logic.

Author: Xwentan

.gitignore

@@ -188,7 +188,7 @@ ChemCoScientist/tests/integration/parse_results
 ChemCoScientist/tests/integration/data/.last_activity
 *db.json
 
-roadmap.txt
+session_snapshots/
 workspace/
 # Execution-graph run snapshots
 graph_runs/

CoScientist/a2a/server.py

@@ -53,12 +53,16 @@ def _attach_opik_tracer(agent: BaseAgent, app_name: str) -> None:
         from opik.integrations.adk import OpikTracer, track_adk_agent_recursive
 
         from CoScientist.config import get_settings
+        from CoScientist.logging.opik_tracer import get_multi_agent_tracer
 
         settings = get_settings()
+        # Ensure tracer env / proxy setup is initialized
+        get_multi_agent_tracer()
+        project_name = settings.opik.opik_project_name or "adk-coscientist"
         tracer = OpikTracer(
             name=f"a2a-{app_name}",
             metadata=_redact(settings.model_dump()),
-            project_name="adk-coscientist",
+            project_name=project_name,
         )
         track_adk_agent_recursive(agent, tracer)
     except Exception as exc:  # never let tracing break the server
@@ -119,6 +123,7 @@ def make_a2a_app(
     """
     _attach_opik_tracer(agent, app_name)
     from CoScientist.logging.event_logger import EventLoggerPlugin
+    from CoScientist.logging.metrics import UsageMetricsPlugin
     from CoScientist.graph.emitter import GraphEmitterPlugin
     from CoScientist.agents.truncation_plugin import ToolResultTruncationPlugin
 
@@ -128,7 +133,12 @@ def make_a2a_app(
         session_service=session_service or InMemorySessionService(),
         artifact_service=InMemoryArtifactService(),
         # truncation MUST be last (ADK early-exits on first non-None after_tool).
-        plugins=[EventLoggerPlugin(), GraphEmitterPlugin(), ToolResultTruncationPlugin()],
+        plugins=[
+            EventLoggerPlugin(),
+            UsageMetricsPlugin(),
+            GraphEmitterPlugin(),
+            ToolResultTruncationPlugin(),
+        ],
     )
     executor = A2aAgentExecutor(runner=runner)
     handler = DefaultRequestHandler(

CoScientist/agent.py

@@ -12,6 +12,7 @@
 from google.adk.apps import App
 
 from CoScientist.logging.event_logger import EventLoggerPlugin
+from CoScientist.logging.metrics import UsageMetricsPlugin
 from CoScientist.graph.plugin import GraphMemoryPlugin
 from CoScientist.graph.research.validator import BackgroundValidatorPlugin
 from CoScientist.agents.truncation_plugin import ToolResultTruncationPlugin
@@ -31,6 +32,7 @@
     root_agent=root_agent,
     plugins=[
         EventLoggerPlugin(),
+        UsageMetricsPlugin(),
         GraphMemoryPlugin(),
         BackgroundValidatorPlugin(),
         ToolResultTruncationPlugin(),

CoScientist/agents/__init__.py

@@ -5,9 +5,16 @@
 system once and re-exports the agent instances under their historical names so
 existing imports keep working.
 """
+import copy
+import logging
+
 from CoScientist.assembly import build_system
-from CoScientist.logging import multi_agent_tracer
+from CoScientist.assembly.schema import load_config
+from CoScientist.logging import get_multi_agent_tracer
 from CoScientist.agents.llm_repair import install_json_repair
+from opik.integrations.adk import track_adk_agent_recursive
+
+logger = logging.getLogger(__name__)
 
 # Guard the LiteLlm tool-call JSON boundary process-wide BEFORE any runner executes:
 # a malformed tool-call payload (qwen truncation / missing comma) must not kill the run.
@@ -32,24 +39,15 @@
 root_agent = orchestrator_agent
 
 # Agents that run as pipeline stages (pre/post) around the orchestrator.
-pipeline_pre_agents = [_system.agent(n) for n in _system.config.pipeline.pre]
-pipeline_post_agents = [_system.agent(n) for n in _system.config.pipeline.post]
+pipeline_pre_agents = [_system.agent(n) for n in _system.config.pipeline.pre if _system.config.agent(n).is_enabled()]
+pipeline_post_agents = [_system.agent(n) for n in _system.config.pipeline.post if _system.config.agent(n).is_enabled()]
 
 # The RUN root: the whole lifecycle (pre → orchestrator → post/aggregator) is one
 # ADK SequentialAgent, driven by a single Runner.run_async so it is ONE invocation
 # = ONE trace, with the Result Aggregator as the terminal child (it reads the graph
 # the orchestrator populated and writes the report). When no pipeline stages are
 # declared, the orchestrator IS the run root (no needless wrapper).
-if pipeline_pre_agents or pipeline_post_agents:
-    from google.adk.agents.sequential_agent import SequentialAgent
-
-    run_root = SequentialAgent(
-        name="ResearchPipeline",
-        description="Full research lifecycle: orchestrator run then report synthesis.",
-        sub_agents=[*pipeline_pre_agents, orchestrator_agent, *pipeline_post_agents],
-    )
-else:
-    run_root = orchestrator_agent
+run_root = _system.run_root
 
 planner_agent = _system.agents.get("PlannerAgent")
 hypotheses_agent = _system.agents.get("HypothesesAgent")
@@ -66,12 +64,116 @@
 tz_agent = _system.agents.get("TZAgent")
 
 # Attach the Opik tracer only when tracing is enabled (see OPIK__ENABLED).
-# Tracking the run root covers the whole SequentialAgent (orchestrator + pipeline
-# stages) so the entire lifecycle lands in ONE trace.
-if multi_agent_tracer is not None:
-    from opik.integrations.adk import track_adk_agent_recursive
+_tracer = get_multi_agent_tracer()
+if _tracer is not None:
+    track_adk_agent_recursive(run_root, _tracer)
+
+
+def build_for_mode():
+    """Build an AgentSystem configured for the current start mode from settings.
+
+    Reads ``settings.web.start_mode``:
+      * ``"planner"`` — PlanningPipelineAgent is root (sequential: PlannerAgent →
+        OrchestratorAgent).
+      * ``"orchestrator"`` — OrchestratorAgent is root, with PlannerAgent
+        added to its subordinates so it can be invoked on demand.
+      * ``"orchestrator_planner"`` — OrchestratorAgent is root, provided with
+        create_plan_tool directly, while PlannerAgent is disabled.
+
+    Other runtime-tunable parameters (e.g. ``max_searches``) are read from
+    ``settings.web`` by individual components at build time.
+
+    Returns:
+        An :class:`~CoScientist.assembly.assembler.AgentSystem`.
+    """
+    from CoScientist.config import get_settings
+    start_mode = get_settings().web.start_mode
+
+    if start_mode in ("planner"):
+        raw_config = load_config()
+        patched = copy.deepcopy(raw_config)
+        pipeline_agent_name = "PlanningPipelineAgent" if "PlanningPipelineAgent" in patched.agents else "InitAgent"
+        if pipeline_agent_name in patched.agents:
+            patched.agents[pipeline_agent_name].root = True
+            patched.agents[pipeline_agent_name].enabled = True
+            patched.agents["OrchestratorAgent"].root = False
+            # In Planner mode the PlannerAgent runs first and its output replaces
+            # the original user query; inject_original_query restores it so the
+            # OrchestratorAgent sees the original request.
+            orch_cb = patched.agents["OrchestratorAgent"].callbacks.before_model
+            if "inject_original_query" not in orch_cb:
+                orch_cb.append("inject_original_query")
+            system = build_system(config=patched)
+        else:
+            logger.warning(
+                "start_mode is set to %r but 'PlanningPipelineAgent' is not present in "
+                "the system config; falling back to default build_system()",
+                start_mode,
+            )
+            system = build_system()
+        _tracer = get_multi_agent_tracer()
+        if _tracer is not None:
+            track_adk_agent_recursive(system.run_root, _tracer)
+        return system
+
+    if start_mode in ("orchestrator_planner", "orchestrator_plan"):
+        raw_config = load_config()
+        patched = copy.deepcopy(raw_config)
+
+        # Make OrchestratorAgent the root.
+        patched.agents["OrchestratorAgent"].root = True
+        for name in ("PlanningPipelineAgent", "InitAgent"):
+            if name in patched.agents:
+                patched.agents[name].root = False
+                patched.agents[name].enabled = False
+
+        # Disable PlannerAgent and remove from Orchestrator's subordinates.
+        if "PlannerAgent" in patched.agents:
+            patched.agents["PlannerAgent"].root = False
+            patched.agents["PlannerAgent"].enabled = False
+
+        orch_subs = patched.agents["OrchestratorAgent"].subordinates
+        if "PlannerAgent" in orch_subs:
+            orch_subs.remove("PlannerAgent")
+
+        # Give OrchestratorAgent the tool for creating/registering plans directly.
+        orch_tools = patched.agents["OrchestratorAgent"].tools
+        if "create_plan_tool" not in orch_tools:
+            orch_tools.append("create_plan_tool")
+
+        system = build_system(config=patched)
+        _tracer = get_multi_agent_tracer()
+        if _tracer is not None:
+            track_adk_agent_recursive(system.run_root, _tracer)
+        return system
+
+    if start_mode != "orchestrator":
+        raise ValueError(
+            f"Unknown start_mode {start_mode!r}; expected 'planner', 'orchestrator', or 'orchestrator_planner'"
+        )
+
+    # Load a fresh config and patch it for orchestrator-as-root mode.
+    raw_config = load_config()
+    patched = copy.deepcopy(raw_config)
+
+    # Make OrchestratorAgent the root.
+    patched.agents["OrchestratorAgent"].root = True
+    for name in ("PlanningPipelineAgent", "InitAgent"):
+        if name in patched.agents:
+            patched.agents[name].root = False
+            patched.agents[name].enabled = False
+
+    # Add PlannerAgent to OrchestratorAgent's subordinates (if not already).
+    orch_subs = patched.agents["OrchestratorAgent"].subordinates
+    if "PlannerAgent" not in orch_subs:
+        orch_subs.insert(0, "PlannerAgent")
 
-    track_adk_agent_recursive(run_root, multi_agent_tracer)
+    # Re-validate the patched config and build.
+    system = build_system(config=patched)
+    _tracer = get_multi_agent_tracer()
+    if _tracer is not None:
+        track_adk_agent_recursive(system.run_root, _tracer)
+    return system
 
 __all__ = [
     "agent_system",
@@ -93,4 +195,5 @@
     "pipeline_pre_agents",
     "pipeline_post_agents",
     "tz_agent",
+    "build_for_mode",
 ]

CoScientist/agents/callbacks/__init__.py

@@ -4,6 +4,7 @@
 <name>` regardless of which submodule defines it.
 """
 from CoScientist.agents.callbacks.critic import (
+    make_plan_critique,
     make_post_action_critique,
     make_pre_action_critique,
 )
@@ -23,15 +24,19 @@
     before_get_task,
     before_tool_reranker_model,
     capture_mcp_artifacts,
+    inject_dataset_context,
     inject_graph_root,
+    make_plan_registration_guard,
     make_unknown_tool_guard,
+    inject_original_query,
     print_research_agent_tool_call,
     redirect_when_no_tools,
 )
 
 __all__ = [
     "make_pre_action_critique",
     "make_post_action_critique",
+    "make_plan_critique",
     "before_model_modifier",
     "med_agent_before_model",
     "papers_agent_before_model",
@@ -44,7 +49,10 @@
     "capture_mcp_artifacts",
     "redirect_when_no_tools",
     "make_unknown_tool_guard",
+    "make_plan_registration_guard",
+    "inject_original_query",
     "before_get_task",
     "inject_graph_root",
+    "inject_dataset_context",
     "sanitize_json_output",
 ]

CoScientist/agents/callbacks/critic.py

@@ -19,10 +19,19 @@
         annotates it with a `_critic` directive when the result is
         insufficient or wrong, leaving the original payload intact.
 
-Both critics are themselves LLM calls returning strict JSON. They are
+A third factory is wired onto the PLANNER instead, independently of the two
+above (system.yaml -> ``PlannerAgent.critic``):
+
+  * `make_plan_critique(instruction)`         -> SessionAgent.plan_critic
+        Reviews the roadmap the planner just registered, BEFORE it is accepted
+        (and before the human sees it). Returns feedback text to send back for
+        one rewrite, or None to accept the plan. The revision budget lives in
+        the SessionAgent (`critic_max_rounds`, default 1), not here.
+
+All three critics are themselves LLM calls returning strict JSON. They are
 factories (not module-level callbacks) because their system prompts embed the
-orchestrator's CURRENT roster — the assembler renders the prompt from the same
-config that wires the sub-agents and passes it in.
+CURRENT roster — the assembler renders the prompt from the same config that
+wires the agents and passes it in.
 """
 
 from __future__ import annotations
@@ -64,6 +73,11 @@ class PostVerdict(str, Enum):
     WRONG = "wrong"
 
 
+class PlanVerdict(str, Enum):
+    APPROVE = "approve"
+    REVISE = "revise"
+
+
 # ---------------------------------------------------------------------------
 # Trajectory parsing (from session history on the callback context)
 # ---------------------------------------------------------------------------
@@ -225,6 +239,10 @@ async def _invoke_critic_llm(system_prompt: str, user_prompt: str) -> Dict[str,
             response_format={"type": "json_object"},
             temperature=0.0,
         )
+        # The critic bypasses the agent tree, so no model callback prices it —
+        # but it runs on every orchestrator turn and is not free.
+        from CoScientist.logging.metrics import record_completion
+        record_completion(resp, model=_CRITIC_MODEL, agent="Critic")
         raw = resp["choices"][0]["message"]["content"]
         return json.loads(raw)
     except Exception as e:
@@ -479,4 +497,46 @@ async def post_action_critique(
 
         return None
 
-    return post_action_critique
+    return post_action_critique
+
+
+# ---------------------------------------------------------------------------
+# Plan critic  (SessionAgent.plan_critic — the PLANNER's own critic)
+# ---------------------------------------------------------------------------
+def make_plan_critique(instruction: str) -> Callable:
+    """Build the planner's plan critic with the given critic prompt.
+
+    Not an ADK callback: an after_model/after_agent callback can only rewrite
+    or replace an output, and a plan critique is worthless unless the PLANNER
+    itself redoes the roadmap. The returned coroutine is handed to the
+    SessionAgent, which owns the generate → review → revise loop and caps it
+    (`critic_max_rounds`, default 1 — the critic gets one say).
+
+    Contract: ``await plan_critique(task, plan) -> feedback | None``. A None
+    (approve, empty feedback, or a failed LLM call) accepts the plan as-is.
+    """
+
+    @track(name="plan_critique")
+    async def plan_critique(task: str, plan: str) -> Optional[str]:
+        user_prompt = (
+            f"ORIGINAL TASK:\n{task or '(not available)'}\n\n"
+            f"PROPOSED PLAN (as registered, in execution order):\n{_truncate(plan, 6000)}\n\n"
+            "Decide whether to approve this plan or send it back for its one "
+            "revision. Respond as strict JSON."
+        )
+
+        print(f"plan critic invoked with such prompt: {user_prompt}")
+
+        payload = await _invoke_critic_llm(instruction, user_prompt)
+        verdict_raw = (payload.get("verdict") or "approve").lower().strip()
+        feedback = (payload.get("feedback") or "").strip()
+
+        print(f"plan critic returned: {payload}")
+
+        # Anything but an explicit, substantiated "revise" accepts the plan:
+        # a revision round the critic cannot justify only costs a rewrite.
+        if verdict_raw != PlanVerdict.REVISE.value or not feedback:
+            return None
+        return feedback
+
+    return plan_critique