Improve agent orchestration, tool summaries, and trace logging.

.env.example

@@ -1,2 +1,7 @@
 EXA_API_KEY=
 FIRECRAWL_API_KEY=
+BORDERLESS_MODEL_ID=Qwen/Qwen3.6-27B
+BORDERLESS_MAX_TOOL_ROUNDS=7
+BORDERLESS_TRACE_DIR=agent_traces
+# Set to 1 if you do not want local JSONL trace logs.
+BORDERLESS_DISABLE_TRACE_LOGS=0

.gitignore

@@ -44,6 +44,7 @@ coverage.xml
 
 # Logs
 *.log
+agent_traces/
 
 # OS
 .DS_Store

ui/inference/config.py

@@ -1,11 +1,13 @@
 # ui/inference/config.py
 from __future__ import annotations
 
+import os
+
 from .tool_schemas import TOOL_SCHEMAS
 from .tool_schemas import think as THINK_SCHEMA
 
-MODEL_ID = "Qwen/Qwen3.6-27B"
-MAX_TOOL_ROUNDS = 5
+MODEL_ID = os.environ.get("BORDERLESS_MODEL_ID", "Qwen/Qwen3.6-27B")
+MAX_TOOL_ROUNDS = int(os.environ.get("BORDERLESS_MAX_TOOL_ROUNDS", "7"))
 
 TOOLS = TOOL_SCHEMAS
 THINK_TOOLS = [THINK_SCHEMA]

ui/inference/respond.py

@@ -198,8 +198,34 @@ def respond(
         yield from yield_response(ui_messages, message, globe_state)
         return
 
+    try:
+        content, reasoning, _ = complete_turn(
+            client,
+            api_messages
+            + [
+                {
+                    "role": "user",
+                    "content": (
+                        "Synthesize the research gathered so far into the best "
+                        "possible partial answer. Clearly label any items that "
+                        "still need verification on official sources."
+                    ),
+                }
+            ],
+            max_tokens=max_tokens,
+            temperature=temperature,
+            top_p=top_p,
+            tools=None,
+        )
+        answer = content or reasoning
+        if answer:
+            yield from yield_response(ui_messages, answer, globe_state)
+            return
+    except Exception:
+        pass
+
     yield from yield_response(
         ui_messages,
-        "I reached the maximum number of tool calls for this request.",
+        "I gathered research but could not finish the full synthesis. Please ask me to summarize the countries already found.",
         globe_state,
     )

ui/inference/tools.py

@@ -7,11 +7,13 @@ from typing import Any
 
 from gradio import ChatMessage
 
+from apis.country_profile import get_country_profiles
 from apis.exa import search_immigration
 from apis.firecrawl import crawl_site, scrape_page
 from ui.globe_commands import apply_update_globe
 
 from .messages import assistant_message_dict
+from .traces import record_tool_trace
 
 
 def truncate(text: str, limit: int = 4000) -> str:
@@ -42,6 +44,8 @@ def _run_tool(
 ) -> tuple[Any, dict[str, Any] | None]:
     if name == "think":
         return {"ok": True}, globe_state
+    if name == "get_country_profile":
+        return get_country_profiles(args["countries"]), globe_state
     if name == "search_immigration_info":
         return (
             search_immigration(
@@ -78,6 +82,84 @@ def _run_tool(
     return {"error": f"Unknown tool: {name}"}, globe_state
 
 
+def _parse_arguments(arguments: str) -> dict[str, Any]:
+    try:
+        parsed = json.loads(arguments or "{}")
+        return parsed if isinstance(parsed, dict) else {}
+    except json.JSONDecodeError:
+        return {}
+
+
+def _load_result(result: str) -> dict[str, Any]:
+    try:
+        parsed = json.loads(result)
+        return parsed if isinstance(parsed, dict) else {}
+    except json.JSONDecodeError:
+        return {}
+
+
+def _join(items: list[str], fallback: str) -> str:
+    clean = [str(item) for item in items if item]
+    return ", ".join(clean) if clean else fallback
+
+
+def _pending_tool_message(tool_name: str, args: dict[str, Any]) -> tuple[str, str]:
+    if tool_name == "get_country_profile":
+        countries = _join(args.get("countries") or [], "selected countries")
+        return "Country profiles", f"Looking up country metadata for {countries}."
+    if tool_name == "search_immigration_info":
+        query = truncate(str(args.get("query") or "immigration sources"), 180)
+        return "Searching sources", f"Searching for official immigration information: {query}"
+    if tool_name == "scrape_web_page":
+        return "Reading official page", f"Reading {args.get('url', 'the selected page')}."
+    if tool_name == "crawl_web_site":
+        return "Crawling source site", f"Crawling related pages from {args.get('url', 'the selected site')}."
+    if tool_name == "update_globe":
+        countries = _join(args.get("countries") or [], "the selected countries")
+        return "Updating globe", f"Showing {countries} on the globe."
+    return f"Using {tool_name}", f"Running `{tool_name}`."
+
+
+def _done_tool_message(tool_name: str, args: dict[str, Any], result: str) -> str:
+    parsed = _load_result(result)
+    if parsed.get("error"):
+        return f"Tool returned an issue: {parsed['error']}"
+
+    if tool_name == "get_country_profile":
+        countries = [
+            country.get("name", "")
+            for country in parsed.get("countries", [])
+            if isinstance(country, dict)
+        ]
+        return f"Found country metadata for {_join(countries, 'the selected countries')}."
+
+    if tool_name == "search_immigration_info":
+        count = parsed.get("num_results", 0)
+        official = parsed.get("official_results", 0)
+        hints = parsed.get("official_domain_hints") or []
+        hint_text = f" Suggested official domains: {_join(hints, 'none')}." if hints else ""
+        return f"Found {count} search results, including {official} likely official source(s).{hint_text}"
+
+    if tool_name == "scrape_web_page":
+        title = parsed.get("title") or args.get("url") or "the page"
+        source = parsed.get("source_url") or parsed.get("url")
+        return f"Extracted official page content from {title}. Source: {source}"
+
+    if tool_name == "crawl_web_site":
+        pages = parsed.get("pages_found", 0)
+        return f"Collected {pages} related page(s) from the official site."
+
+    if tool_name == "update_globe":
+        countries = [
+            country.get("name", country.get("iso2", ""))
+            for country in parsed.get("countries", [])
+            if isinstance(country, dict)
+        ]
+        return f"Updated the globe with {_join(countries, 'the selected countries')}."
+
+    return f"`{tool_name}` completed."
+
+
 def execute_tool_calls(
     api_messages: list[dict[str, Any]],
     ui_messages: list[ChatMessage],
@@ -90,19 +172,16 @@ def execute_tool_calls(
     for tool_call in tool_calls:
         tool_name = tool_call["function"]["name"]
         tool_args = tool_call["function"]["arguments"]
+        parsed_args = _parse_arguments(tool_args)
         started = time.monotonic()
 
         if tool_name == "think":
-            try:
-                args = json.loads(tool_args or "{}")
-            except json.JSONDecodeError:
-                args = {}
-            thought = str(args.get("thought") or "").strip()
+            thought = str(parsed_args.get("thought") or "").strip()
 
             ui_messages.append(
                 ChatMessage(
                     role="assistant",
-                    content="Thinking…",
+                    content="Planning the research approach...",
                     metadata={
                         "title": "Thinking",
                         "status": "pending",
@@ -111,24 +190,18 @@ def execute_tool_calls(
             )
             yield ui_messages, globe_state
 
-            if thought:
-                for index in range(len(thought)):
-                    ui_messages[-1] = ChatMessage(
-                        role="assistant",
-                        content=thought[: index + 1],
-                        metadata={
-                            "title": "Thinking",
-                            "status": "pending",
-                        },
-                    )
-                    yield ui_messages, globe_state
-
             result, globe_state = run_tool(
                 tool_name,
                 tool_args,
                 globe_state=globe_state,
             )
             duration = time.monotonic() - started
+            record_tool_trace(
+                tool_name=tool_name,
+                arguments=tool_args,
+                result=result,
+                duration=duration,
+            )
             ui_messages[-1] = ChatMessage(
                 role="assistant",
                 content=thought if thought else "Thinking complete.",
@@ -150,15 +223,13 @@ def execute_tool_calls(
             )
             continue
 
+        title, pending_message = _pending_tool_message(tool_name, parsed_args)
         ui_messages.append(
             ChatMessage(
                 role="assistant",
-                content=(
-                    f"Calling `{tool_name}` with arguments:\n"
-                    f"```json\n{tool_args}\n```"
-                ),
+                content=pending_message,
                 metadata={
-                    "title": f"🛠️ Used tool {tool_name}",
+                    "title": title,
                     "status": "pending",
                 },
             )
@@ -171,16 +242,18 @@ def execute_tool_calls(
             globe_state=globe_state,
         )
         duration = time.monotonic() - started
+        record_tool_trace(
+            tool_name=tool_name,
+            arguments=tool_args,
+            result=result,
+            duration=duration,
+        )
 
         ui_messages[-1] = ChatMessage(
             role="assistant",
-            content=(
-                f"Calling `{tool_name}` with arguments:\n"
-                f"```json\n{tool_args}\n```\n\n"
-                f"Result:\n```json\n{truncate(result)}\n```"
-            ),
+            content=_done_tool_message(tool_name, parsed_args, result),
             metadata={
-                "title": f"🛠️ Used tool {tool_name}",
+                "title": title,
                 "status": "done",
                 "duration": duration,
             },

ui/inference/traces.py

@@ -0,0 +1,46 @@
+"""Optional JSONL trace logging for sharing Borderless agent sessions."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+TRACE_DIR = Path(os.environ.get("BORDERLESS_TRACE_DIR", "agent_traces"))
+TRACE_RESULT_LIMIT = 6000
+
+
+def _compact_result(result: str) -> str:
+    if len(result) <= TRACE_RESULT_LIMIT:
+        return result
+    return result[:TRACE_RESULT_LIMIT] + "\n... (truncated)"
+
+
+def record_tool_trace(
+    *,
+    tool_name: str,
+    arguments: str,
+    result: str,
+    duration: float,
+) -> None:
+    """Write one tool call to JSONL so sessions can be shared after a demo."""
+    if os.environ.get("BORDERLESS_DISABLE_TRACE_LOGS") == "1":
+        return
+
+    try:
+        TRACE_DIR.mkdir(parents=True, exist_ok=True)
+        path = TRACE_DIR / time.strftime("borderless-%Y%m%d.jsonl")
+        payload: dict[str, Any] = {
+            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "tool_name": tool_name,
+            "arguments": arguments,
+            "duration_seconds": round(duration, 3),
+            "result": _compact_result(result),
+        }
+        with path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(payload, ensure_ascii=False) + "\n")
+    except OSError:
+        # Trace export should never break the live research experience.
+        return