nava-agent 0.2.0__py3-none-any.whl

nava/agents/factory.py

@@ -0,0 +1,141 @@
+import uuid
+import hashlib
+from typing import Optional, List, Dict
+from datetime import datetime
+from nava.core.schemas import AgentSpec, AgentState, AgentType, AgentStatus, Outcome, ToolRequest
+from nava.agents.templates import Templates, StaticAgentTemplate
+from nava.tools.registry import ToolRegistry
+from nava.gateway.pipeline import PolicyEngine, BudgetEngine
+
+class AgentFactory:
+    def __init__(self, registry: ToolRegistry, policy_engine: PolicyEngine, budget_engine: BudgetEngine):
+        self.registry = registry
+        self.policy_engine = policy_engine
+        self.budget_engine = budget_engine
+
+    def spawn_agent(self, spec: AgentSpec, parent_state: AgentState) -> AgentState:
+        # 1. Budget & Depth Enforcement (Section 9.4)
+        if not self.budget_engine.check_spawn(parent_state):
+            raise RuntimeError(f"Budget exhausted for spawning new agents in task {parent_state.budget_ref}")
+            
+        if spec.max_children > 0 and len(parent_state.child_agent_ids) >= spec.max_children:
+            raise ValueError(f"Exceeds max children limit of {spec.max_children}")
+        
+        # 2. Template Resolution (Section 9.2)
+        template = Templates.get_template(spec.requested_role)
+        
+        is_dynamic = template is None
+        agent_type = AgentType.DYNAMIC if is_dynamic else AgentType.STATIC
+        template_id = template.template_id if template else None
+        
+        # 3. Dynamic Fallback & Scope Synthesis
+        base_permission_scope = []
+        base_tool_scope = []
+        
+        if not is_dynamic:
+            base_permission_scope = template.permission_scope.copy()
+            base_tool_scope = spec.requested_tools.copy() # Templates don't explicitly list tool scopes, they list permission scopes.
+        else:
+            # Dynamically synthesize scope by introspecting requested tools
+            for tool_name in spec.requested_tools:
+                try:
+                    t_def = self.registry.get_tool(tool_name)
+                    if t_def:
+                        base_tool_scope.append(tool_name)
+                        base_permission_scope.extend(t_def.permissions_required)
+                except KeyError:
+                    pass
+            base_permission_scope = list(set(base_permission_scope))
+
+        # 4. Permission Intersection (Section 9.3)
+        # child_scope = parent_scope ∩ requested_scope ∩ policy_allowed_scope
+        
+        intersected_permissions = []
+        intersected_tools = []
+        
+        # Helper to check scope match with wildcards (e.g. *, filesystem.*)
+        def scope_matches(scope_pattern: str, target: str) -> bool:
+            if scope_pattern == "*" or scope_pattern == target:
+                return True
+            if scope_pattern.endswith(".*"):
+                prefix = scope_pattern[:-2]
+                return target.startswith(prefix)
+            return False
+
+        def is_in_scope_list(scope_list: List[str], target: str) -> bool:
+            return any(scope_matches(pattern, target) for pattern in scope_list)
+
+        # Helper to query policy
+        def is_allowed_by_policy(scope: str) -> bool:
+            mock_req = ToolRequest(
+                request_id="policy_check",
+                agent_id="factory",
+                tool_name=scope,
+                arguments={},
+                requested_scope=scope
+            )
+            eval_result = self.policy_engine.evaluate(mock_req, parent_state)
+            return eval_result == Outcome.ALLOW
+            
+        # Intersect Permissions
+        for req_perm in spec.requested_permission_scope:
+            if is_in_scope_list(parent_state.permission_scope, req_perm) and is_in_scope_list(base_permission_scope, req_perm):
+                if is_allowed_by_policy(req_perm):
+                    if req_perm not in intersected_permissions:
+                        intersected_permissions.append(req_perm)
+                    
+        # Intersect Tools and their inherent permissions
+        for req_tool in spec.requested_tools:
+            if (req_tool in parent_state.tool_scope or is_in_scope_list(parent_state.tool_scope, req_tool)) and req_tool in base_tool_scope:
+                t_def = self.registry.get_tool(req_tool)
+                if not t_def:
+                    continue
+                
+                # Enforce invariant: A tool can only be granted if ALL its required permissions
+                # fall within the agent's base template scope and parent scope.
+                tool_permitted = True
+                for p in t_def.permissions_required:
+                    if not is_in_scope_list(base_permission_scope, p) or not is_in_scope_list(parent_state.permission_scope, p):
+                        tool_permitted = False
+                        break
+                        
+                if tool_permitted:
+                    intersected_tools.append(req_tool)
+                    
+                    # Auto-inject the tool's required permissions if permitted
+                    for p in t_def.permissions_required:
+                        if is_in_scope_list(parent_state.permission_scope, p) and p not in intersected_permissions:
+                            if is_allowed_by_policy(p):
+                                intersected_permissions.append(p)
+
+        # Intersect Credentials (Phase 6)
+        # Credential scope must be a subset of permissions per Section 17.3
+        intersected_credentials = []
+        for req_tool in intersected_tools:
+            t_def = self.registry.get_tool(req_tool)
+            if t_def and t_def.required_credentials:
+                for perm in t_def.permissions_required:
+                    if is_in_scope_list(parent_state.credential_scope, perm) and perm not in intersected_credentials:
+                        if perm in intersected_permissions: # Critical invariant check
+                            intersected_credentials.append(perm)
+
+        # 5. State Initialization
+        # 5. Mint AgentState
+        state = AgentState(
+            agent_id=f"agt-{uuid.uuid4().hex[:8]}",
+            parent_agent_id=parent_state.agent_id if parent_state else None,
+            role=spec.requested_role,
+            display_label=spec.display_label,
+            type=agent_type,
+            template_id=template_id,
+            goal=spec.goal,
+            permission_scope=intersected_permissions,
+            credential_scope=intersected_credentials,
+            tool_scope=intersected_tools,
+            depth=(parent_state.depth + 1) if parent_state else 0,
+            status=AgentStatus.PENDING,
+            ttl=spec.ttl,
+            expires_at=datetime.utcnow() + spec.ttl,
+            budget_ref=parent_state.budget_ref
+        )
+        return state

nava/agents/planner.py

@@ -0,0 +1,146 @@
+import os
+import uuid
+import hashlib
+import datetime
+from typing import List, Dict, Any, Optional
+from langchain_core.messages import SystemMessage, HumanMessage
+from pydantic import BaseModel, Field
+from nava.core.schemas import AgentSpec, Priority
+from nava.core.llm import get_llm
+
+class SubGoal(BaseModel):
+    role: str = Field(description="The formal role of the agent (must be a known template, or 'DynamicAgent' if none fit).")
+    display_label: Optional[str] = Field(None, description="A human-readable descriptive name (e.g. 'WebResearchAgent', 'DataAnalysisAgent', 'PDFAnalyzer') used only for audit logs.")
+    goal: str = Field(description="The specific goal for this sub-agent.")
+    required_tools: List[str] = Field(description="The tools this agent will need.")
+    required_permissions: List[str] = Field(description="The permissions this agent will need.")
+    stage: int = Field(default=1, description="The execution stage number (1, 2, 3...). Sub-goals with the same stage number execute concurrently in parallel.")
+    is_parallel: bool = Field(default=True, description="Whether this sub-goal can run concurrently with others in the same stage.")
+
+class GoalPlan(BaseModel):
+    thoughts: str = Field(description="Your step-by-step reasoning for breaking down the objective into parallel and sequential execution stages.")
+    sub_goals: List[SubGoal] = Field(description="List of sub-goals organized by execution stages.")
+
+def compute_dedup_hash(role: str, goal: str, tools: List[str]) -> str:
+    clean_goal = goal.strip().lower()
+    tools_str = ",".join(sorted(tools))
+    raw = f"{role}:{clean_goal}:{tools_str}".encode('utf-8')
+    return hashlib.sha256(raw).hexdigest()[:16]
+
+class GoalPlanner:
+    def __init__(self, available_templates: List[str], ceiling_tools: List[str], ceiling_permissions: List[str], budget_engine=None, registry=None):
+        self.available_templates = available_templates
+        self.ceiling_tools = ceiling_tools
+        self.ceiling_permissions = ceiling_permissions
+        self.budget_engine = budget_engine
+        self.registry = registry
+        if os.environ.get("NAVA_TEST_MODE") == "1":
+            self.llm = None
+        else:
+            self.llm = get_llm()
+
+
+    def plan(self, objective: str, parent_id: str, budget_ref: str = None) -> List[AgentSpec]:
+        if os.environ.get("NAVA_TEST_MODE") == "1":
+            # Mock plan for testing
+            return [
+                AgentSpec(
+                    request_id=f"req-{uuid.uuid4().hex[:8]}",
+                    requested_role="DocumentAgent",
+                    goal=objective,
+                    parent_agent_id=parent_id,
+                    requested_tools=["file.write"],
+                    requested_permission_scope=["filesystem.write"],
+                    ttl=datetime.timedelta(minutes=15),
+                    max_steps=10,
+                    max_tokens=5000,
+                    max_children=2,
+                    dedup_hash=compute_dedup_hash("DocumentAgent", objective, ["file.write"]),
+                    stage=1,
+                    is_parallel=True
+                )
+            ]
+
+        prompt_path = os.path.join(os.path.dirname(__file__), "..", "prompts", "planner_prompt.txt")
+        with open(prompt_path, "r", encoding="utf-8") as f:
+            prompt_template = f.read()
+            
+        system_prompt = prompt_template.format(
+            templates=self.available_templates,
+            tools=self.ceiling_tools,
+            permissions=self.ceiling_permissions
+        )
+        
+        sys_msg = SystemMessage(content=system_prompt)
+        human_msg = HumanMessage(content=f"Objective: {objective}")
+
+        structured_llm = self.llm.with_structured_output(GoalPlan)
+        try:
+            if self.budget_engine and budget_ref:
+                self.budget_engine.consume_internal_llm_call(budget_ref, tokens=500)
+            plan: GoalPlan = structured_llm.invoke([sys_msg, human_msg])
+        except Exception as e:
+            print(f"Planner failed: {e}")
+            raise e
+
+        print(f"\n[Orchestrator Planner Thinking]:\n{plan.thoughts}\n")
+        print("[Orchestrator Plan]:")
+        for i, sg in enumerate(plan.sub_goals):
+            print(f"  [Stage {sg.stage}] {sg.role} ({sg.display_label or sg.role}) → {sg.goal}")
+            print(f"     Tools: {sg.required_tools}")
+
+        specs = []
+        for sg in plan.sub_goals:
+            req_tools = list(sg.required_tools or [])
+            # Ensure baseline tools for specialized roles (guards against small LLM tool omissions)
+            if sg.role == "CodingAgent":
+                for bt in ["file.write", "file.read", "code.replace_content", "code.search", "test.run"]:
+                    if bt not in req_tools and (not self.ceiling_tools or bt in self.ceiling_tools or "*" in self.ceiling_tools):
+                        req_tools.append(bt)
+            elif sg.role == "ResearchAgent":
+                for bt in ["search.web", "browser.navigate", "browser.extract_text", "file.write", "file.read"]:
+                    if bt not in req_tools and (not self.ceiling_tools or bt in self.ceiling_tools or "*" in self.ceiling_tools):
+                        req_tools.append(bt)
+            elif sg.role == "ComputerAgent":
+                for bt in ["desktop.screenshot", "desktop.click", "desktop.type", "desktop.get_screen_size"]:
+                    if bt not in req_tools and (not self.ceiling_tools or bt in self.ceiling_tools or "*" in self.ceiling_tools):
+                        req_tools.append(bt)
+            elif sg.role == "TerminalAgent":
+                for bt in ["terminal.execute", "file.read"]:
+                    if bt not in req_tools and (not self.ceiling_tools or bt in self.ceiling_tools or "*" in self.ceiling_tools):
+                        req_tools.append(bt)
+
+            dedup = compute_dedup_hash(sg.role, sg.goal, req_tools)
+            
+            # Auto-synthesize requested_permission_scope from required_tools if registry is available
+            derived_perms = list(sg.required_permissions or [])
+            if self.registry:
+                for t_name in req_tools:
+                    try:
+                        t_def = self.registry.get_tool(t_name)
+                        if t_def:
+                            for p in t_def.permissions_required:
+                                if p not in derived_perms:
+                                    derived_perms.append(p)
+                    except Exception:
+                        pass
+
+            specs.append(AgentSpec(
+                request_id=f"req-{uuid.uuid4().hex[:8]}",
+                requested_role=sg.role,
+                display_label=sg.display_label or sg.role,
+                goal=sg.goal,
+                parent_agent_id=parent_id,
+                requested_tools=req_tools,
+                requested_permission_scope=derived_perms,
+                ttl=datetime.timedelta(minutes=30),
+                max_steps=20,
+                max_tokens=10000,
+                max_children=2,
+                dedup_hash=dedup,
+                stage=sg.stage,
+                is_parallel=sg.is_parallel
+            ))
+            
+        return specs
+

nava/agents/runtime/browser_agent.py

@@ -0,0 +1,171 @@
+import json
+import re
+from typing import Dict, Any, List
+from langgraph.graph import StateGraph, END
+from langchain_core.messages import SystemMessage, HumanMessage, AIMessage
+from pydantic import BaseModel
+from nava.core.schemas import AgentState, ToolRequest
+from nava.core.llm import get_llm
+from nava.governance.dom_sanitizer import sanitize_dom
+
+# Max history entries to keep (sliding window = last N message pairs)
+_MAX_HISTORY_PAIRS = 4  # 4 pairs = 8 messages = last 4 rounds of thought
+
+# Pattern to strip sensitive data from error messages
+_SENSITIVE_ERR_PATTERN = re.compile(
+    r'(api[_-]?key|token|password|secret|credential)[=:]\s*\S+',
+    re.IGNORECASE
+)
+
+def _sanitize_error(error_str: str) -> str:
+    """Strip API keys, tokens, and internal paths from error messages."""
+    sanitized = _SENSITIVE_ERR_PATTERN.sub('[REDACTED]', error_str)
+    # Also strip absolute Windows/Unix paths
+    sanitized = re.sub(r'[A-Z]:\\[\w\\]+', '[PATH]', sanitized)
+    sanitized = re.sub(r'/(?:home|usr|etc|var|tmp)/[\w/]+', '[PATH]', sanitized)
+    return sanitized
+
+
+class BrowserPlan(BaseModel):
+    thoughts: str
+    tool_name: str
+    arguments: dict
+
+def build_browser_agent(registry=None) -> StateGraph:
+    """Builds the Tier 2 cyclic BrowserAgent execution graph."""
+    
+    workflow = StateGraph(dict)
+
+    def plan_node(state: dict):
+        agent_state: AgentState = state["agent_state"]
+        observation = state.get("observation", "No observation yet.")
+        consumed = state.get("consumed_steps", 0)
+        max_steps = state.get("max_steps", 15)
+        
+        if consumed >= max_steps:
+            state["plan"] = "FINISH"
+            state["error"] = "LOOP_BUDGET_EXHAUSTED"
+            return state
+
+        # If observation is raw HTML, sanitize it before feeding to LLM
+        if isinstance(observation, dict) and "html" in observation:
+            sanitized_html, is_flagged = sanitize_dom(
+                observation["html"],
+                ledger=state.get("gateway").audit_ledger if state.get("gateway") else None
+            )
+            observation = f"Sanitized DOM (flagged={is_flagged}):\n{sanitized_html[:5000]}..."
+        
+        # If observation is extracted text, just truncate it
+        if isinstance(observation, dict) and "text" in observation:
+            text = observation["text"]
+            observation = f"Extracted Page Text:\n{text[:8000]}"
+            if len(text) > 8000:
+                observation += "\n... [TRUNCATED — use browser.save_to_scratch to save the full text]"
+        
+        # Inject tool schemas
+        tool_schemas = []
+        if registry:
+            for t_name in agent_state.tool_scope:
+                t_def = registry.get_tool(t_name)
+                if t_def:
+                    tool_schemas.append(f"- {t_name}: {t_def.description}\n  Schema: {json.dumps(t_def.input_schema)}")
+        tool_schemas_str = "\n".join(tool_schemas)
+
+        llm = get_llm()
+        structured_llm = llm.with_structured_output(BrowserPlan)
+        
+        import os
+        prompt_path = os.path.join(os.path.dirname(__file__), "..", "..", "prompts", "browser_prompt.txt")
+        with open(prompt_path, "r", encoding="utf-8") as f:
+            prompt_template = f.read()
+            
+        system_prompt = prompt_template.format(
+            goal=agent_state.goal,
+            tool_schemas=tool_schemas_str
+        )
+        messages = [SystemMessage(content=system_prompt)]
+        
+        # Sliding window history — keep only the last N pairs
+        history = state.get("history", [])
+        if len(history) > _MAX_HISTORY_PAIRS * 2:
+            # Summarize older history into a single message
+            old_messages = history[:-((_MAX_HISTORY_PAIRS * 2))]
+            summary_parts = []
+            for msg in old_messages:
+                content = msg.content if hasattr(msg, 'content') else str(msg)
+                summary_parts.append(content[:200])
+            summary = "Summary of earlier actions:\n" + "\n".join(summary_parts)
+            messages.append(HumanMessage(content=summary))
+            # Keep recent history
+            history = history[-((_MAX_HISTORY_PAIRS * 2)):]
+        
+        for h in history:
+            messages.append(h)
+            
+        messages.append(HumanMessage(content=f"Current Observation:\n{observation}\n\nWhat is your next action?"))
+        
+        try:
+            plan = structured_llm.invoke(messages)
+            
+            # Record our own thought/action to history for the next iteration
+            # Truncate observation in history to save context
+            obs_summary = str(observation)[:500]
+            history.append(HumanMessage(content=f"Observation: {obs_summary}"))
+            history.append(AIMessage(content=f"Thought: {plan.thoughts}\nAction: {plan.tool_name}({json.dumps(plan.arguments)})"))
+            state["history"] = history
+            
+            if plan.tool_name == "finish" or plan.tool_name.lower() == "none" or plan.tool_name.lower() == "stop":
+                state["plan"] = "FINISH"
+                state["final_answer"] = plan.thoughts
+                state["tool_request"] = None
+            else:
+                import uuid
+                state["plan"] = plan.thoughts
+                state["tool_request"] = ToolRequest(
+                    request_id=f"req-{uuid.uuid4().hex[:8]}",
+                    agent_id=agent_state.agent_id,
+                    tool_name=plan.tool_name,
+                    arguments=plan.arguments,
+                    requested_scope=plan.tool_name
+                )
+        except Exception as e:
+            sanitized_err = _sanitize_error(str(e))
+            print(f"[BrowserAgent] Failed to plan: {sanitized_err}")
+            state["plan"] = "FINISH"
+            state["error"] = sanitized_err
+            state["tool_request"] = None
+            
+        state["consumed_steps"] = consumed + 1
+        return state
+
+    def execute_node(state: dict):
+        req = state.get("tool_request")
+        if not req:
+            return state
+            
+        gateway = state.get("gateway")
+        if not gateway:
+            state["observation"] = "Error: Gateway not available."
+            return state
+            
+        print(f"\n[BrowserAgent] Executing: {req.tool_name}({req.arguments})")
+        print(f"[BrowserAgent] Thoughts: {state.get('plan')}")
+        
+        result = gateway.process_request(req)
+        state["receipt"] = result
+        state["observation"] = result.result_data
+        return state
+
+    def should_continue(state: dict):
+        if state.get("plan") == "FINISH" or state.get("error"):
+            return "end"
+        return "execute"
+
+    workflow.add_node("plan", plan_node)
+    workflow.add_node("execute", execute_node)
+    
+    workflow.set_entry_point("plan")
+    workflow.add_conditional_edges("plan", should_continue, {"execute": "execute", "end": END})
+    workflow.add_edge("execute", "plan")
+
+    return workflow.compile()

nava/agents/runtime/coding_agent.py

@@ -0,0 +1,117 @@
+import os
+import json
+import uuid
+from typing import TypedDict, Optional
+from langgraph.graph import StateGraph, END
+from langchain_core.messages import SystemMessage, HumanMessage
+from pydantic import BaseModel
+from nava.core.schemas import AgentState, AgentStatus, ToolRequest
+from nava.core.llm import get_llm
+
+class CodingPlan(BaseModel):
+    thoughts: str
+    tool_name: str
+    arguments: dict
+
+def build_coding_agent(registry=None) -> StateGraph:
+    """Builds the Tier 2 cyclic coding agent execution graph."""
+    
+    workflow = StateGraph(dict)
+
+    def plan_node(state: dict):
+        agent_state: AgentState = state["agent_state"]
+        payload = state.get("payload", {})
+        observation = state.get("observation")
+        
+        if agent_state.status != AgentStatus.RUNNING:
+            agent_state.status = AgentStatus.RUNNING
+            
+        tool_schemas_str = "No tools available."
+        if registry:
+            tool_schemas = []
+            for t_name in agent_state.tool_scope:
+                t_def = registry.get_tool(t_name)
+                if t_def:
+                    tool_schemas.append(f"- {t_name}: {t_def.description}\n  Schema: {json.dumps(t_def.input_schema)}")
+            if tool_schemas:
+                tool_schemas_str = "\n".join(tool_schemas)
+
+        llm = get_llm()
+        structured_llm = llm.with_structured_output(CodingPlan)
+        
+        prompt_path = os.path.join(os.path.dirname(__file__), "..", "..", "prompts", "coding_agent_prompt.txt")
+        with open(prompt_path, "r", encoding="utf-8") as f:
+            prompt_template = f.read()
+
+        # Extract skill catalog from orchestrator payload (injected by SkillManager)
+        skill_catalog = payload.get("context", "")
+
+        system_prompt = prompt_template.format(
+            goal=agent_state.goal,
+            tool_schemas_str=tool_schemas_str,
+            skill_catalog=skill_catalog
+        )
+                        
+        sys_msg = SystemMessage(content=system_prompt)
+        
+        history = state.get("history", [])
+        
+        content = f"Payload: {json.dumps(payload)}\n"
+        if history:
+            content += "\n[YOUR PREVIOUS ACTIONS & OBSERVATIONS]\n" + "\n".join(history) + "\n"
+            
+        if observation:
+            content += f"\n[LATEST OBSERVATION]\nResult: {json.dumps(observation)}\n"
+            
+        human_msg = HumanMessage(content=content)
+        
+        try:
+            decision = structured_llm.invoke([sys_msg, human_msg])
+            print(f"\n[CodingAgent Thinking]:\n{decision.thoughts}\n")
+        except Exception as e:
+            print(f"\n[CodingAgent Error]: LLM generation or parsing failed: {e}")
+            decision = CodingPlan(thoughts=f"Fatal error parsing structured output: {e}", tool_name="FINISH", arguments={})
+        
+        new_history = history.copy()
+        if observation:
+            # Truncate large observations before appending to history so we don't blow up the context window
+            obs_str = json.dumps(observation)
+            if len(obs_str) > 1500:
+                obs_str = obs_str[:1500] + "... [TRUNCATED for history context]"
+            new_history.append(f"Observation: {obs_str}")
+            
+        new_history.append(f"Action taken: {decision.tool_name}, args: {json.dumps(decision.arguments)}")
+        state["history"] = new_history
+        
+        if decision.tool_name == "FINISH":
+            state["tool_request"] = None
+            state["plan"] = "FINISH"
+            return state
+
+        # Resolve correct scope for this specific tool
+        resolved_scope = agent_state.permission_scope[0] if agent_state.permission_scope else ""
+        if registry:
+            try:
+                t_def = registry.get_tool(decision.tool_name)
+                if t_def and t_def.permissions_required:
+                    resolved_scope = t_def.permissions_required[0]
+            except Exception:
+                pass
+            
+        req = ToolRequest(
+            request_id=f"req-{uuid.uuid4().hex[:8]}",
+            agent_id=agent_state.agent_id,
+            tool_name=decision.tool_name,
+            arguments=decision.arguments,
+            requested_scope=resolved_scope
+        )
+        state["tool_request"] = req
+        state["plan"] = decision.tool_name
+        return state
+
+    workflow.add_node("plan", plan_node)
+    
+    workflow.set_entry_point("plan")
+    workflow.add_edge("plan", END)
+    
+    return workflow.compile()