Merge MythosHarness history into OpenMythos

.env.example

@@ -0,0 +1,3 @@
+OPENAI_API_KEY=sk-your-api-key-here
+OPENAI_BASE_URL=https://api.openai.com/v1
+OPENAI_MODEL=gpt-3.5-turbo

.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg-info/
+dist/
+build/
+
+# Virtual environment
+.venv/
+venv/
+
+# Environment variables
+.env
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Gradio (caches temp files)
+gradio_cached_examples/

agent/__init__.py

@@ -0,0 +1,20 @@
+from .agent import Agent
+from .tools import Tool, tool, fetch_webpage, FETCH_WEBPAGE_TOOL, SHELL_TOOL
+from .mcp import MCPClient, mcp_tool, load_mcp_tools, load_all_mcp_tools, MCP_SERVERS
+from .shell import ShellManager, get_shell_manager
+
+__all__ = [
+    "Agent",
+    "Tool",
+    "tool",
+    "fetch_webpage",
+    "FETCH_WEBPAGE_TOOL",
+    "SHELL_TOOL",
+    "MCPClient",
+    "mcp_tool",
+    "load_mcp_tools",
+    "load_all_mcp_tools",
+    "MCP_SERVERS",
+    "ShellManager",
+    "get_shell_manager",
+]

agent/agent.py

@@ -0,0 +1,412 @@
+import json
+from typing import Any, Generator
+
+from openai import OpenAI
+
+from .tools import Tool
+from .mcp import MCPClient, load_mcp_tools, load_all_mcp_tools
+
+# ---------------------------------------------------------------------------
+# Streaming event contract
+# ---------------------------------------------------------------------------
+# Each yield from Agent.stream() is a dict with a "type" key:
+#
+#   {"type": "text",     "content": "partial text"}
+#   {"type": "reasoning","content": "model thinking"}
+#   {"type": "tool_call", "name": str, "arguments": '{"url":"..."}'}
+#   {"type": "tool_output","name": str, "arguments": str, "content": "result", "partial": bool}
+#   {"type": "done",     "content": "full assistant response"}
+#   {"type": "error",    "content": "error message"}
+# ---------------------------------------------------------------------------
+
+
+class Agent:
+    """OpenAI-compatible tool-calling agent with streaming.
+
+    When ``register_final_message_tool()`` is used the model **must** call
+    ``final_message`` to signal completion — plain text responses without
+    the tool will keep the conversation loop alive.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        model: str,
+        max_iterations: int = 150,
+        system_prompt: str | None = None,
+    ) -> None:
+        self.client = OpenAI(base_url=base_url, api_key=api_key)
+        self.model = model
+        self._tools: list[Tool] = []
+        self._final_tool_name: str | None = None
+        self._max_iterations = max_iterations
+        self.system_prompt = system_prompt
+        self._tool_results: dict[str, str] = {}  # tool_call_id → full result
+
+    # ------------------------------------------------------------------
+    # Tool registration
+    # ------------------------------------------------------------------
+
+    def register_tool(self, tool: Tool) -> None:
+        self._tools.append(tool)
+
+    def register_read_tool(self) -> None:
+        """Register a tool to read truncated tool responses by line range."""
+        results_cache = self._tool_results
+
+        def _read(tool_call_id: str, start_line: int, num_lines: int = 50) -> str:
+            """Read more lines from a truncated tool response.
+
+            tool_call_id (required): The tool_call_id from the truncated response
+            start_line (required): Line number to start reading from
+            num_lines: Number of lines to read (default 50)
+            """
+            full = results_cache.get(tool_call_id)
+            if full is None:
+                return f"Error: No result found for tool_call_id '{tool_call_id}'"
+            lines = full.split("\n")
+            total = len(lines)
+            if start_line >= total:
+                return f"Error: start_line {start_line} >= total lines {total}"
+            end = min(start_line + num_lines, total)
+            chunk = "\n".join(lines[start_line:end])
+            remaining = total - end
+            header = f"Lines {start_line}-{end} of {total}"
+            if remaining > 0:
+                header += f" ({remaining} lines remaining)"
+            return f"{header}\n\n{chunk}"
+
+        self._tools.append(
+            Tool(
+                name="read_tool_response",
+                description="Read more lines from a truncated tool response. Use when a previous tool output was truncated.",
+                parameters={
+                    "type": "object",
+                    "properties": {
+                        "tool_call_id": {
+                            "type": "string",
+                            "description": "The tool_call_id from the truncated response",
+                        },
+                        "start_line": {
+                            "type": "integer",
+                            "description": "Line number to start reading from (0-indexed)",
+                        },
+                        "num_lines": {
+                            "type": "integer",
+                            "description": "Number of lines to read (default 50)",
+                        },
+                    },
+                    "required": ["tool_call_id", "start_line"],
+                },
+                handler=_read,
+            )
+        )
+
+    def register_mcp(self, url: str, headers: dict[str, str] | None = None) -> list[Tool]:
+        """Connect to an MCP server and register all its tools.
+
+        Returns the list of registered Tool instances.
+        """
+        tools = load_mcp_tools(url=url, headers=headers)
+        self._tools.extend(tools)
+        return tools
+
+    def register_all_mcp(self) -> dict[str, list[Tool]]:
+        """Load tools from all pre-configured MCP servers.
+
+        Returns ``{server_name: [Tool, ...]}`` and registers them.
+        """
+        all_tools = load_all_mcp_tools()
+        for server_tools in all_tools.values():
+            self._tools.extend(server_tools)
+        return all_tools
+
+    def register_final_message_tool(self) -> None:
+        """Register a no-input ``final_message`` tool the model **must** call
+        to signal that it is done.
+
+        Until the model calls this tool the agent keeps looping — plain
+        text responses or other tool calls will not end the conversation.
+
+        The tool call is handled internally: no ``tool_call`` /
+        ``tool_output`` events are yielded and the caller only sees a
+        ``done`` event.
+        """
+        self._final_tool_name = "final_message"
+        self._tools.append(
+            Tool(
+                name="final_message",
+                description=(
+                    "Signal that you have completed your response and want "
+                    "to end the conversation. Call this ONLY when you are "
+                    "truly done. Until you call this tool, the conversation "
+                    "will continue. Means you will multiple times answer the"
+                    "same question or can get stuck in loops if you never call it."
+                ),
+                parameters={"type": "object", "properties": {}, "required": []},
+                handler=lambda: "",
+            )
+        )
+
+    # ------------------------------------------------------------------
+    # Streaming loop
+    # ------------------------------------------------------------------
+
+    def stream(self, messages: list[dict]) -> Generator[dict, None, None]:
+        """Yield streaming events until the model calls ``final_message``.
+
+        *messages* is mutated in-place — after the generator completes it
+        contains the full conversation history.
+        """
+        iteration = 0
+
+        # Inject system prompt once at the front if set
+        if self.system_prompt and (
+            not messages or messages[0].get("role") != "system"
+        ):
+            messages.insert(0, {"role": "system", "content": self.system_prompt})
+
+        while True:
+            iteration += 1
+            if iteration > self._max_iterations:
+                yield {
+                    "type": "error",
+                    "content": f"Agent did not call final_message after "
+                    f"{self._max_iterations} iterations",
+                }
+                return
+
+            specs = [t.to_openai_spec() for t in self._tools] if self._tools else None
+
+            collected_content = ""
+            collected_tool_calls: dict[int, dict] = {}
+
+            kwargs: dict[str, Any] = dict(
+                model=self.model,
+                messages=messages,
+                stream=True,
+                extra_body={"thinking_token_budget": 2000}
+            )
+            if specs:
+                kwargs["tools"] = specs
+
+            try:
+                stream = self.client.chat.completions.create(**kwargs)
+            except Exception as exc:
+                yield {"type": "error", "content": str(exc)}
+                return
+
+            for chunk in stream:
+                cd = chunk.to_dict()
+                choices = cd.get("choices", [])
+                if not choices:
+                    continue
+                delta = choices[0].get("delta", {})
+
+                reasoning = delta.get("reasoning_content") or delta.get("reasoning")
+                if reasoning:
+                    yield {"type": "reasoning", "content": reasoning}
+
+                # Text content
+                content = delta.get("content", "")
+                if content:
+                    collected_content += content
+                    yield {"type": "text", "content": content}
+
+                # Tool call fragments
+                for tc in delta.get("tool_calls", []):
+                    idx = tc.get("index", 0)
+                    if idx not in collected_tool_calls:
+                        collected_tool_calls[idx] = {
+                            "id": tc.get("id", ""),
+                            "function": {"name": "", "arguments": ""},
+                        }
+                    if tc.get("id"):
+                        collected_tool_calls[idx]["id"] = tc["id"]
+                    fn = tc.get("function", {})
+                    if fn.get("name"):
+                        collected_tool_calls[idx]["function"]["name"] += fn["name"]
+                    if fn.get("arguments"):
+                        collected_tool_calls[idx]["function"]["arguments"] += fn[
+                            "arguments"
+                        ]
+
+            # --- Handle tool calls ---
+            if collected_tool_calls:
+                tool_call_list: list[dict[str, Any]] = []
+                for idx in sorted(collected_tool_calls.keys()):
+                    tc = collected_tool_calls[idx]
+                    tool_call_list.append(
+                        {
+                            "id": tc["id"],
+                            "type": "function",
+                            "function": {
+                                "name": tc["function"]["name"],
+                                "arguments": tc["function"]["arguments"],
+                            },
+                        }
+                    )
+
+                # Assistant message with tool_calls (appended before we decide
+                # whether to continue or stop so the conversation is coherent)
+                assistant_msg: dict[str, Any] = {
+                    "role": "assistant",
+                    "content": collected_content or None,
+                }
+                assistant_msg["tool_calls"] = tool_call_list
+                messages.append(assistant_msg)
+
+                # --- final_message check (handled internally) ---
+                if self._final_tool_name:
+                    for tc_spec in tool_call_list:
+                        if tc_spec["function"]["name"] == self._final_tool_name:
+                            # Dummy tool result so history stays well-formed
+                            messages.append(
+                                {
+                                    "role": "tool",
+                                    "tool_call_id": tc_spec["id"],
+                                    "content": "",
+                                }
+                            )
+                            messages.append(
+                                {"role": "assistant", "content": collected_content}
+                            )
+                            yield {"type": "done", "content": collected_content}
+                            return
+
+                # --- Execute real tools ---
+                for tc_spec in tool_call_list:
+                    tname = tc_spec["function"]["name"]
+                    try:
+                        targs = json.loads(tc_spec["function"]["arguments"])
+                    except json.JSONDecodeError:
+                        targs = {}
+
+                    yield {
+                        "type": "tool_call",
+                        "name": tname,
+                        "arguments": tc_spec["function"]["arguments"],
+                    }
+
+                    tool_obj = next(
+                        (t for t in self._tools if t.name == tname), None
+                    )
+
+                    if tool_obj is None:
+                        result_str = f"Error: Tool '{tname}' not found"
+                        self._tool_results[tc_spec["id"]] = result_str
+                        yield {
+                            "type": "tool_output",
+                            "name": tname,
+                            "arguments": tc_spec["function"]["arguments"],
+                            "content": result_str,
+                        }
+                        messages.append({
+                            "role": "tool",
+                            "tool_call_id": tc_spec["id"],
+                            "content": result_str,
+                        })
+                        continue
+
+                    # Streamable tool — yield partial results
+                    if tool_obj.streamable:
+                        accumulated = ""
+                        last_chunk = ""
+                        try:
+                            for chunk in tool_obj.stream(**targs):
+                                accumulated += chunk
+                                last_chunk = chunk
+                                # Truncate display but keep full for read_tool_response
+                                display = accumulated
+                                if len(display) > 5_000:
+                                    lines = display.split("\n")
+                                    char_count = 0
+                                    cut_line = 0
+                                    for i, line in enumerate(lines):
+                                        char_count += len(line) + 1
+                                        if char_count > 5_000:
+                                            cut_line = i
+                                            break
+                                    display = "\n".join(lines[:cut_line])
+                                yield {
+                                    "type": "tool_output",
+                                    "name": tname,
+                                    "arguments": tc_spec["function"]["arguments"],
+                                    "content": display,
+                                    "partial": True,
+                                }
+                            # Mark final yield as non-partial
+                            display = accumulated
+                            if len(display) > 5_000:
+                                lines = display.split("\n")
+                                char_count = 0
+                                cut_line = 0
+                                for i, line in enumerate(lines):
+                                    char_count += len(line) + 1
+                                    if char_count > 5_000:
+                                        cut_line = i
+                                        break
+                                display = "\n".join(lines[:cut_line])
+                            yield {
+                                "type": "tool_output",
+                                "name": tname,
+                                "arguments": tc_spec["function"]["arguments"],
+                                "content": display,
+                                "partial": False,
+                            }
+                            result_str = accumulated
+                        except Exception as e:
+                            result_str = f"Error executing {tname}: {e}"
+                    else:
+                        # Regular tool — single result
+                        try:
+                            result_str = str(tool_obj.run(**targs))
+                        except Exception as e:
+                            result_str = f"Error executing {tname}: {e}"
+
+                    # Store full result and truncate for message history
+                    self._tool_results[tc_spec["id"]] = result_str
+                    lines = result_str.split("\n")
+                    if len(result_str) > 5_000:
+                        char_count = 0
+                        cut_line = 0
+                        for i, line in enumerate(lines):
+                            char_count += len(line) + 1
+                            if char_count > 5_000:
+                                cut_line = i
+                                break
+                        truncated = "\n".join(lines[:cut_line])
+                        remaining = len(lines) - cut_line
+                        result_str = f"{truncated}\n\n...[{remaining} lines truncated — use read_tool_response tool_call_id=\"{tc_spec['id']}\" start_line={cut_line} to read more]"
+
+                    # Final tool_output (non-partial) for history
+                    if not tool_obj.streamable:
+                        yield {
+                            "type": "tool_output",
+                            "name": tname,
+                            "arguments": tc_spec["function"]["arguments"],
+                            "content": result_str,
+                        }
+
+                    messages.append({
+                        "role": "tool",
+                        "tool_call_id": tc_spec["id"],
+                        "content": result_str,
+                    })
+
+                continue  # Loop back — model can call more tools or final_message
+
+            # --- No tool calls ---
+            if self._final_tool_name:
+                # final_message is expected but wasn't called — keep the
+                # conversation loop alive so the model gets another chance
+                messages.append(
+                    {"role": "assistant", "content": collected_content}
+                )
+                continue  # Loop back
+
+            # No final_message tool registered — normal end
+            messages.append({"role": "assistant", "content": collected_content})
+            yield {"type": "done", "content": collected_content}
+            break

agent/mcp.py

@@ -0,0 +1,261 @@
+"""MCP (Model Context Protocol) client for remote tool servers.
+
+Supports Streamable HTTP transport (JSON-RPC 2.0 over HTTP).
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any
+
+import httpx
+
+from .tools import Tool
+
+
+# ---------------------------------------------------------------------------
+# MCP Client
+# ---------------------------------------------------------------------------
+
+
+class MCPClient:
+    """Connect to a remote MCP server via Streamable HTTP transport."""
+
+    def __init__(
+        self,
+        url: str,
+        headers: dict[str, str] | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.url = url
+        self.headers = headers or {}
+        self.timeout = timeout
+        self._session_id: str | None = None
+        self._initialized = False
+
+    # ------------------------------------------------------------------
+    # Low-level JSON-RPC
+    # ------------------------------------------------------------------
+
+    def _request(self, method: str, params: dict[str, Any] | None = None) -> Any:
+        """Send a JSON-RPC request and return the result."""
+        payload: dict[str, Any] = {
+            "jsonrpc": "2.0",
+            "id": str(uuid.uuid4()),
+            "method": method,
+        }
+        if params is not None:
+            payload["params"] = params
+
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+            **self.headers,
+        }
+        if self._session_id:
+            headers["Mcp-Session-Id"] = self._session_id
+
+        with httpx.Client(timeout=self.timeout) as client:
+            resp = client.post(self.url, json=payload, headers=headers)
+
+            # Capture session ID from response
+            sid = resp.headers.get("mcp-session-id")
+            if sid:
+                self._session_id = sid
+
+            resp.raise_for_status()
+            content_type = resp.headers.get("content-type", "")
+
+            # Handle SSE response
+            if "text/event-stream" in content_type:
+                return self._parse_sse_response(resp.text)
+
+            # Handle JSON response
+            data = resp.json()
+            if "error" in data:
+                raise RuntimeError(f"MCP error: {data['error']}")
+            return data.get("result")
+
+    def _parse_sse_response(self, text: str) -> Any:
+        """Parse SSE response text, extracting JSON-RPC results."""
+        result = None
+        for line in text.split("\n"):
+            line = line.strip()
+            if line.startswith("data:"):
+                data_str = line[len("data:") :].strip()
+                if data_str:
+                    try:
+                        data = json.loads(data_str)
+                        if "result" in data:
+                            result = data["result"]
+                        elif "error" in data:
+                            raise RuntimeError(f"MCP error: {data['error']}")
+                    except json.JSONDecodeError:
+                        continue
+        return result
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def initialize(self) -> dict[str, Any]:
+        """Initialize the MCP session."""
+        result = self._request(
+            "initialize",
+            {
+                "protocolVersion": "2025-03-26",
+                "capabilities": {},
+                "clientInfo": {"name": "mythos-agent", "version": "0.1.0"},
+            },
+        )
+        self._initialized = True
+        # Send initialized notification (no response expected)
+        self._notify("notifications/initialized", {})
+        return result or {}
+
+    def _notify(self, method: str, params: dict[str, Any]) -> None:
+        """Send a JSON-RPC notification (no id, no response expected)."""
+        payload = {"jsonrpc": "2.0", "method": method, "params": params}
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+            **self.headers,
+        }
+        if self._session_id:
+            headers["Mcp-Session-Id"] = self._session_id
+
+        with httpx.Client(timeout=self.timeout) as client:
+            client.post(self.url, json=payload, headers=headers)
+
+    # ------------------------------------------------------------------
+    # Tool discovery
+    # ------------------------------------------------------------------
+
+    def list_tools(self) -> list[dict[str, Any]]:
+        """List available tools from the server."""
+        if not self._initialized:
+            self.initialize()
+        result = self._request("tools/list", {})
+        return (result or {}).get("tools", [])
+
+    # ------------------------------------------------------------------
+    # Tool execution
+    # ------------------------------------------------------------------
+
+    def call_tool(self, name: str, arguments: dict[str, Any]) -> Any:
+        """Call a tool on the server."""
+        if not self._initialized:
+            self.initialize()
+        return self._request("tools/call", {"name": name, "arguments": arguments})
+
+
+# ---------------------------------------------------------------------------
+# MCP Tool wrapper
+# ---------------------------------------------------------------------------
+
+
+def _json_schema_type_to_python(type_str: str) -> type:
+    """Map JSON Schema type to Python type."""
+    mapping = {"string": str, "integer": int, "number": float, "boolean": bool, "array": list, "object": dict}
+    return mapping.get(type_str, str)
+
+
+def mcp_tool(client: MCPClient, mcp_tool_def: dict[str, Any]) -> Tool:
+    """Wrap an MCP tool definition as a local Tool instance.
+
+    Args:
+        client: Connected MCPClient.
+        mcp_tool_def: Tool dict from ``tools/list`` response.
+    """
+    name = mcp_tool_def["name"]
+    description = mcp_tool_def.get("description", "")
+    input_schema = mcp_tool_def.get("inputSchema", {})
+
+    # Convert inputSchema to OpenAI-style parameters
+    properties: dict[str, dict] = {}
+    for param_name, param_def in input_schema.get("properties", {}).items():
+        prop: dict[str, Any] = {"type": param_def.get("type", "string")}
+        if "description" in param_def:
+            prop["description"] = param_def["description"]
+        if "enum" in param_def:
+            prop["enum"] = param_def["enum"]
+        properties[param_name] = prop
+
+    required = input_schema.get("required", [])
+
+    parameters = {
+        "type": "object",
+        "properties": properties,
+        "required": required,
+    }
+
+    def handler(**kwargs: Any) -> str:
+        result = client.call_tool(name, kwargs)
+        # Extract text content from MCP result
+        if isinstance(result, dict) and "content" in result:
+            parts = []
+            for block in result["content"]:
+                if isinstance(block, dict) and block.get("type") == "text":
+                    parts.append(block.get("text", ""))
+            return "\n".join(parts) if parts else json.dumps(result)
+        return json.dumps(result) if not isinstance(result, str) else result
+
+    return Tool(name=name, description=description, parameters=parameters, handler=handler)
+
+
+# ---------------------------------------------------------------------------
+# Convenience: connect and load all tools
+# ---------------------------------------------------------------------------
+
+
+def load_mcp_tools(url: str, headers: dict[str, str] | None = None) -> list[Tool]:
+    """Connect to an MCP server and return all its tools as Tool instances."""
+    client = MCPClient(url=url, headers=headers)
+    client.initialize()
+    tools_defs = client.list_tools()
+    return [mcp_tool(client, td) for td in tools_defs]
+
+
+# ---------------------------------------------------------------------------
+# Pre-configured MCP servers
+# ---------------------------------------------------------------------------
+
+MCP_SERVERS: dict[str, dict[str, Any]] = {
+    "exa": {
+        "url": "https://mcp.exa.ai/mcp",
+        "description": "Web search via Exa",
+    },
+    "context7": {
+        "url": "https://mcp.context7.com/mcp",
+        "description": "Library documentation lookup",
+    },
+    "grep_app": {
+        "url": "https://mcp.grep.app",
+        "description": "GitHub code search via grep.app",
+    },
+}
+
+
+def load_all_mcp_tools(
+    servers: dict[str, dict[str, Any]] | None = None,
+) -> dict[str, list[Tool]]:
+    """Load tools from all configured MCP servers.
+
+    Returns:
+        ``{server_name: [Tool, ...]}``
+    """
+    if servers is None:
+        servers = MCP_SERVERS
+
+    result: dict[str, list[Tool]] = {}
+    for name, cfg in servers.items():
+        try:
+            result[name] = load_mcp_tools(
+                url=cfg["url"],
+                headers=cfg.get("headers"),
+            )
+        except Exception as e:
+            print(f"[MCP] Failed to load {name}: {e}")
+            result[name] = []
+    return result

agent/responses.py

@@ -0,0 +1,29 @@
+"""
+Streaming event types yielded by Agent.stream().
+
+Each event is a plain dict with at least a ``"type"`` key.
+"""
+
+# ── Text chunk ──────────────────────────────────────────────────────────
+# {"type": "text",      "content": "partial assistant message"}
+TEXT = "text"
+
+# ── Reasoning (e.g. DeepSeek R1 chain-of-thought) ──────────────────────
+# {"type": "reasoning", "content": "model thinking"}
+REASONING = "reasoning"
+
+# ── Tool was called by the model ────────────────────────────────────────
+# {"type": "tool_call",   "name": "fetch_webpage", "arguments": '{"url":"..."}'}
+TOOL_CALL = "tool_call"
+
+# ── Tool execution output ───────────────────────────────────────────────
+# {"type": "tool_output", "name": "fetch_webpage", "content": "<html>..."}
+TOOL_OUTPUT = "tool_output"
+
+# ── Final response (no more tool calls) ─────────────────────────────────
+# {"type": "done",       "content": "full assistant message"}
+DONE = "done"
+
+# ── Fatal error ─────────────────────────────────────────────────────────
+# {"type": "error",      "content": "API key invalid"}
+ERROR = "error"

agent/shell.py

@@ -0,0 +1,180 @@
+"""Shell manager for running interactive subprocesses with streaming output."""
+
+from __future__ import annotations
+
+import subprocess
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import IO
+
+
+@dataclass
+class ShellSession:
+    """A running shell session."""
+
+    session_id: str
+    process: subprocess.Popen[str]
+    output_buffer: list[str] = field(default_factory=list)
+    last_read_pos: int = 0
+    started_at: float = field(default_factory=time.time)
+    closed: bool = False
+
+    @property
+    def pid(self) -> int | None:
+        return self.process.pid
+
+    @property
+    def returncode(self) -> int | None:
+        return self.process.returncode
+
+    def read_new_output(self) -> str:
+        """Read new output since last read."""
+        new_lines = self.output_buffer[self.last_read_pos :]
+        self.last_read_pos = len(self.output_buffer)
+        return "".join(new_lines)
+
+    def get_full_output(self) -> str:
+        """Get all output."""
+        return "".join(self.output_buffer)
+
+    def is_running(self) -> bool:
+        """Check if process is still running."""
+        return self.process.poll() is None
+
+    def close(self) -> None:
+        """Close the session."""
+        if not self.closed:
+            self.closed = True
+            try:
+                self.process.terminate()
+                self.process.wait(timeout=5)
+            except Exception:
+                try:
+                    self.process.kill()
+                except Exception:
+                    pass
+
+
+class ShellManager:
+    """Manages multiple shell sessions with streaming output."""
+
+    def __init__(self, default_timeout: float = 15.0) -> None:
+        self.sessions: dict[str, ShellSession] = {}
+        self._lock = threading.Lock()
+        self.default_timeout = default_timeout
+
+    def start(
+        self,
+        session_id: str,
+        command: str,
+        cwd: str | None = None,
+        env: dict[str, str] | None = None,
+    ) -> ShellSession:
+        """Start a new shell session."""
+        with self._lock:
+            # Close existing session with same ID
+            if session_id in self.sessions:
+                self.sessions[session_id].close()
+
+            # Use shell=True for interactive commands
+            process = subprocess.Popen(
+                command,
+                shell=True,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+                bufsize=1,
+                cwd=cwd,
+                env=env,
+            )
+
+            session = ShellSession(session_id=session_id, process=process)
+            self.sessions[session_id] = session
+
+            # Start output reader thread
+            thread = threading.Thread(
+                target=self._read_output, args=(session,), daemon=True
+            )
+            thread.start()
+
+            return session
+
+    def _read_output(self, session: ShellSession) -> None:
+        """Read output from process in background thread."""
+        assert session.process.stdout is not None
+        try:
+            for line in session.process.stdout:
+                with self._lock:
+                    session.output_buffer.append(line)
+        except Exception:
+            pass
+        finally:
+            with self._lock:
+                session.closed = True
+
+    def send_input(self, session_id: str, input_text: str) -> bool:
+        """Send input to a running session."""
+        with self._lock:
+            session = self.sessions.get(session_id)
+            if session is None or not session.is_running():
+                return False
+            if session.process.stdin is None:
+                return False
+            try:
+                session.process.stdin.write(input_text + "\n")
+                session.process.stdin.flush()
+                return True
+            except Exception:
+                return False
+
+    def get_output(self, session_id: str) -> str | None:
+        """Get full output from a session."""
+        with self._lock:
+            session = self.sessions.get(session_id)
+            if session is None:
+                return None
+            return session.get_full_output()
+
+    def poll_output(self, session_id: str) -> str | None:
+        """Get new output since last poll."""
+        with self._lock:
+            session = self.sessions.get(session_id)
+            if session is None:
+                return None
+            return session.read_new_output()
+
+    def is_running(self, session_id: str) -> bool:
+        """Check if a session is still running."""
+        with self._lock:
+            session = self.sessions.get(session_id)
+            if session is None:
+                return False
+            return session.is_running()
+
+    def close(self, session_id: str) -> None:
+        """Close a session."""
+        with self._lock:
+            session = self.sessions.get(session_id)
+            if session:
+                session.close()
+
+    def close_all(self) -> None:
+        """Close all sessions."""
+        with self._lock:
+            for session in self.sessions.values():
+                session.close()
+            self.sessions.clear()
+
+
+# Global shell manager instance
+_shell_manager: ShellManager | None = None
+
+
+def get_shell_manager() -> ShellManager:
+    """Get or create the global shell manager."""
+    global _shell_manager
+    if _shell_manager is None:
+        _shell_manager = ShellManager()
+    return _shell_manager

agent/tools.py

@@ -0,0 +1,272 @@
+from markitdown import MarkItDown
+from typing import Any, Callable, Generator, get_type_hints
+import inspect
+import requests
+
+
+def python_type_to_json_schema(tp: type) -> str:
+    """Map a Python type to a JSON Schema type string."""
+    mapping = {
+        str: "string",
+        int: "integer",
+        float: "number",
+        bool: "boolean",
+        list: "array",
+        dict: "object",
+    }
+    return mapping.get(tp, "string")
+
+class Tool:
+    """A callable tool the agent can invoke."""
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        parameters: dict,
+        handler: Callable[..., str],
+        streamable: bool = False,
+    ) -> None:
+        self.name = name
+        self.description = description
+        self.parameters = parameters
+        self.handler = handler
+        self.streamable = streamable
+
+    def to_openai_spec(self) -> dict:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    def run(self, **kwargs: Any) -> str:
+        return self.handler(**kwargs)
+
+    def stream(self, **kwargs: Any) -> Generator[str, None, None]:
+        """Yield partial results for streamable tools.
+
+        Override in subclasses or use streamable=True with a generator handler.
+        """
+        if self.streamable and callable(self.handler):
+            result = self.handler(**kwargs)
+            if isinstance(result, Generator):
+                yield from result
+            else:
+                yield str(result)
+        else:
+            yield self.handler(**kwargs)
+
+
+def _parse_docstring(docstring: str) -> tuple[str, dict[str, tuple[bool, str]]]:
+    """Parse a tool docstring into description and param metadata.
+
+    Returns:
+        (description, {param_name: (required, description)})
+
+    Expected format:
+        First line: tool description.
+        Subsequent lines: ``param_name (required): description`` or
+        ``param_name: description``.
+    """
+    lines = (docstring or "").strip().split("\n")
+    description = lines[0].strip()
+    param_info: dict[str, tuple[bool, str]] = {}
+
+    for line in lines[1:]:
+        line = line.strip()
+        if not line:
+            continue
+        # Match: param_name (required): description
+        #    or: param_name: description
+        if ":" not in line:
+            continue
+        key, desc = line.split(":", 1)
+        key = key.strip()
+        desc = desc.strip()
+        required = False
+        if key.endswith("(required)"):
+            required = True
+            key = key[: -len("(required)")].strip()
+        if key:
+            param_info[key] = (required, desc)
+
+    return description, param_info
+
+
+def tool(fn: Callable[..., str]) -> Tool:
+    """Decorator that converts a function into a Tool instance.
+
+    Extracts name, description (first line of docstring), and parameters
+    from the function's type hints and signature.
+
+    Docstring format:
+        First line: tool description.
+        Subsequent lines: ``param_name (required): description`` or
+        ``param_name: description``.
+    """
+    name = fn.__name__
+    docstring = fn.__doc__ or ""
+    description, param_info = _parse_docstring(docstring)
+
+    hints = get_type_hints(fn)
+    sig = inspect.signature(fn)
+
+    properties: dict[str, dict] = {}
+    required: list[str] = []
+
+    for param_name, param in sig.parameters.items():
+        if param_name in hints:
+            param_schema: dict[str, Any] = {
+                "type": python_type_to_json_schema(hints[param_name])
+            }
+            # Enrich with docstring info if present
+            if param_name in param_info:
+                doc_required, doc_desc = param_info[param_name]
+                if doc_desc:
+                    param_schema["description"] = doc_desc
+                # Docstring (required) overrides signature default check
+                if doc_required:
+                    required.append(param_name)
+                elif param.default is inspect.Parameter.empty:
+                    required.append(param_name)
+            elif param.default is inspect.Parameter.empty:
+                required.append(param_name)
+            properties[param_name] = param_schema
+
+    parameters = {
+        "type": "object",
+        "properties": properties,
+        "required": required,
+    }
+
+    return Tool(
+        name=name,
+        description=description,
+        parameters=parameters,
+        handler=fn,
+    )
+
+
+@tool
+def fetch_webpage(url: str) -> str:
+    """Fetch a webpage and return its text content.
+
+    url (required): The URL to fetch
+    """
+    try:
+        jina_ai_url = "https://r.jina.ai/"
+        response = requests.get(jina_ai_url + url)
+        response.raise_for_status()
+        return response.text
+    except Exception as e:
+        md = MarkItDown()
+        return md.convert(url).text_content
+
+FETCH_WEBPAGE_TOOL = fetch_webpage  # @tool already makes it a Tool instance
+
+
+# ---------------------------------------------------------------------------
+# Shell tool (streamable)
+# ---------------------------------------------------------------------------
+
+import time
+import uuid as _uuid
+from .shell import get_shell_manager
+
+
+def _shell_handler(
+    command: str,
+    session_id: str = "",
+    input_text: str = "",
+) -> str:
+    """Run shell commands interactively.
+
+    command (required): The shell command to execute (omit when checking output or sending input)
+    session_id: Session ID to check output or send input to (omit to start new command)
+    input_text: Text to send to running session's stdin
+
+    How it works:
+    - Start new command: returns session_id immediately (non-blocking)
+    - Check output: call with session_id to get current output
+    - Send input: call with session_id + input_text
+    - Command runs in background, never blocks the agent
+    """
+    manager = get_shell_manager()
+
+    existing_session = session_id and session_id in manager.sessions
+
+    # Send input to running session
+    if existing_session and input_text:
+        sent = manager.send_input(session_id, input_text)
+        if not sent:
+            return f"Error: Session '{session_id}' closed"
+        time.sleep(0.3)
+        output = manager.poll_output(session_id)
+        running = manager.is_running(session_id)
+        status = "running" if running else f"exited (code {manager.sessions[session_id].returncode})"
+        if output:
+            return f"[{session_id}] {status}:\n{output}"
+        return f"[{session_id}] {status} (no new output)"
+
+    # Check output of existing session
+    if existing_session:
+        output = manager.get_output(session_id)
+        running = manager.is_running(session_id)
+        code = manager.sessions[session_id].returncode
+        status = "running" if running else f"exited with code {code}"
+        if output:
+            return f"[{session_id}] {status}:\n{output}"
+        return f"[{session_id}] {status}"
+
+    # Start new command
+    sid = session_id or str(_uuid.uuid4())[:8]
+    session = manager.start(sid, command)
+
+    # Wait a bit to capture initial output (fast commands finish here)
+    time.sleep(0.5)
+    initial = session.read_new_output()
+    running = session.is_running()
+
+    if not running:
+        # Command finished quickly
+        code = session.process.returncode
+        final = session.read_new_output()
+        output = (initial + final).strip()
+        if output:
+            return f"[{sid}] exited with code {code}:\n{output}"
+        return f"[{sid}] exited with code {code}"
+
+    # Command still running — return status so model can check later
+    if initial:
+        return f"[{sid}] running (PID {session.pid}):\n{initial}\n\nCall again with session_id=\"{sid}\" to check output."
+    return f"[{sid}] running (PID {session.pid})\n\nCall again with session_id=\"{sid}\" to check output."
+
+
+SHELL_TOOL = Tool(
+    name="shell",
+    description="Run shell commands interactively. Start command -> returns session_id. Call again with session_id to check output or send input. Never blocks.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "command": {
+                "type": "string",
+                "description": "The shell command to execute (omit when checking output or sending input)",
+            },
+            "session_id": {
+                "type": "string",
+                "description": "Session ID to check output or send input to (omit to start new command)",
+            },
+            "input_text": {
+                "type": "string",
+                "description": "Text to send to running session's stdin",
+            },
+        },
+        "required": ["command"],
+    },
+    handler=_shell_handler,
+    streamable=False,
+)

app.css

@@ -0,0 +1,396 @@
+@import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&display=swap');
+
+.gradio-container, .main {
+  padding: 0 !important;
+  --layout-gap: 0 !important;
+}
+
+footer {
+  display: none !important;
+}
+
+html {
+  scroll-behavior: smooth;
+}
+
+#main-row {
+  height: 100vh;
+  max-height: 1500px;
+}
+
+button[aria-label="Clear"] {
+  display: none;
+}
+
+#chat-column {
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  padding: 0;
+  overflow: hidden;
+  position: relative;
+}
+
+#chatbot {
+  flex: 1;
+  min-height: 100px;
+  border: 0;
+}
+
+.sidebar {
+  border-right: 1px solid var(--border-color-primary);
+  box-shadow: none;
+}
+
+.sidebar-parent:has(.sidebar.open:not(.right)) {
+  padding-left: 320px;
+}
+
+.sidebar-content {
+  position: relative;
+  padding: 50px 0 0 0 !important;
+  background: none;
+}
+
+.sidebar-content::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background: url("/gradio_api/file=static/svg/logo.svg") no-repeat top;
+  background-size: 180px 52px;
+  pointer-events: none;
+  z-index: 0;
+}
+
+.toggle-button {
+  top: 10px;
+}
+
+/* New Conversation button - top spacing */
+.sidebar > :first-child {
+  margin-bottom: 8px;
+}
+
+/* Sidebar buttons (New/Del) */
+#main-row .sidebar button {
+  transition: all 0.15s ease;
+}
+
+#main-row .sidebar button:hover {
+  transform: translateY(-1px);
+}
+
+.sidebar-content .form {
+  border: 0;
+  background: transparent;
+}
+
+.wrap {
+  gap: 0;
+}
+
+/* Conversation items — card-style list */
+#conversations-radio {
+  padding: 0;
+  border: 0;
+  background: transparent;
+}
+
+#conversations-radio > div:last-child {
+  display: grid;
+  gap: 2px;
+}
+
+#conversations-radio input[type="radio"] {
+  opacity: 0;
+  position: absolute;
+  width: 0;
+  height: 0;
+}
+
+#conversations-radio span[data-testid="block-info"] {
+  display: none;
+}
+
+#conversations-radio label {
+  padding: 10px 14px;
+  margin: 0;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  transition: all 0.2s ease;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  background: transparent;
+  color: var(--button-secondary-text-color);
+  border-bottom: 1px solid var(--border-color-primary);
+}
+
+label span {
+  margin: 0;
+}
+
+.icon-button-wrapper {
+  display: hidden;
+}
+
+/* --- Chat Message Animations --- */
+@keyframes messageSlideIn {
+  from {
+    opacity: 0;
+    transform: translateY(16px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+/* Animate new messages as they appear */
+#chatbot [data-testid="bot"],
+#chatbot [data-testid="user"],
+#chatbot [class*="message"] {
+  animation: messageSlideIn 0.35s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+/* --- Input Area — Docked Bottom --- */
+
+
+/* --- Send / Stop Button Micro-animations --- */
+#send-btn, #stop-btn {
+  font-size: 0;
+  height: 100%;
+  min-width: 40px;
+  transition: transform 0.15s ease, opacity 0.15s ease;
+  cursor: pointer;
+  padding: 0;
+}
+
+#send-btn::after {
+  content: "";
+  display: inline-block;
+  width: 20px;
+  height: 20px;
+  background: url("/gradio_api/file=static/svg/send.svg") no-repeat center;
+  background-size: contain;
+}
+
+#stop-btn::after {
+  content: "";
+  display: inline-block;
+  width: 20px;
+  height: 20px;
+  background: url("/gradio_api/file=static/svg/stop.svg") no-repeat center;
+  background-size: contain;
+}
+
+/* --- Custom Scrollbars --- */
+#chatbot::-webkit-scrollbar {
+  width: 6px;
+}
+
+#chatbot::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+#chatbot::-webkit-scrollbar-thumb {
+  background: var(--border-color-primary);
+  transition: background 0.2s ease;
+}
+
+#chatbot::-webkit-scrollbar-thumb:hover {
+  background: var(--neutral-400);
+}
+
+/* Sidebar scrollbar — thinner, subtle */
+.sidebar::-webkit-scrollbar {
+  width: 4px;
+}
+
+.sidebar::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.sidebar::-webkit-scrollbar-thumb {
+  background: var(--border-color-primary);
+  border-radius: 2px;
+}
+
+.input-container textarea {
+  background: var(--background-fill-secondary) !important;
+}
+
+.bubble-wrap {
+  background: var(--background-fill-primary) !important;
+}
+
+/* ============================================
+   LANDING PAGE - Terminal-inspired Design
+   ============================================ */
+
+#landing-page-container {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--background-fill-primary);
+  z-index: 10;
+  pointer-events: auto;
+}
+
+#landing-page {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.landing-content {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 32px;
+  padding: 40px;
+  max-width: 600px;
+  width: 100%;
+}
+
+/* Logo styling */
+.landing-logo {
+  margin-bottom: 100px !important;
+}
+
+.landing-logo svg {
+  height: 60px;
+  width: auto;
+}
+
+/* Hide landing page when chat has messages */
+#landing-page-container.hidden {
+  display: none !important;
+}
+
+.landing-prompt {
+  bottom: 5%;
+  position: absolute;
+  text-align: center;
+}
+
+body:not(.dark) .landing-logo img, body:not(.dark) .sidebar-content::before {
+  filter: invert(0.8);
+}
+
+/* ============================================
+   INPUT ROW - Terminal-style Global
+   ============================================ */
+
+/* When landing page is visible, center the input row */
+#chat-column.landing-active #input-row {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translateX(-50%);
+  width: 100%;
+  max-width: 600px;
+  z-index: 20;
+}
+
+#chat-column.landing-active #send-btn,
+#chat-column.landing-active #stop-btn {
+  align-self: stretch;
+  min-width: 56px;
+  padding: 0 8px;
+  height: auto;
+}
+
+/* When landing page is hidden (chat active), keep input at bottom */
+#chat-column:not(.landing-active) #input-row {
+  position: relative;
+  bottom: 3%;
+  left: auto;
+  transform: none;
+  max-width: none;
+}
+
+/* Terminal-style input row */
+#input-row {
+  z-index: 15;
+  position: relative;
+}
+
+#input-row .form {
+  background: rgba(255, 255, 255, 0.03) !important;
+  border: 1px solid rgba(255, 255, 255, 0.1) !important;
+  border-radius: 8px !important;
+  font-family: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace !important;
+  transition: all 0.2s ease !important;
+}
+
+#input-row .form:focus-within {
+  border-color: rgba(255, 255, 255, 0.3) !important;
+  background: rgba(255, 255, 255, 0.05) !important;
+  box-shadow: 0 0 0 2px rgba(255, 255, 255, 0.05) !important;
+}
+
+/* Terminal cursor effect on input */
+#input-row textarea,
+#input-row input[type="text"] {
+  font-family: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace !important;
+  caret-color: var(--body-text-color) !important;
+  caret-shape: block !important;
+}
+
+/* Blinking cursor animation for input */
+@keyframes inputCursorBlink {
+  0%, 50% { border-right-color: var(--body-text-color); }
+  51%, 100% { border-right-color: transparent; }
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+  .landing-content {
+    padding: 20px;
+    gap: 24px;
+  }
+
+  .landing-logo svg {
+    height: 40px;
+  }
+}
+
+/* Center chat column on larger screens */
+@media (min-width: 749px) {
+  #chat-column {
+    max-width: 748px;
+    margin: 0 auto;
+  }
+}
+
+/* Apply monospace font to body for terminal feel */
+body, .gradio-container {
+  font-family: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace !important;
+}
+
+/* Chatbot styling when empty */
+#chatbot:empty,
+#chatbot .empty-state {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+}
+
+/* Ensure proper z-index stacking */
+#chatbot {
+  z-index: 5;
+}
+
+.message-wrap {
+  margin-bottom: 40px;
+}

app.py

@@ -0,0 +1,443 @@
+import time
+import uuid
+import gradio as gr
+from dotenv import load_dotenv
+from agent import Agent, FETCH_WEBPAGE_TOOL, SHELL_TOOL
+import os
+from pathlib import Path
+
+load_dotenv()
+gr.set_static_paths("static/")
+
+_SYSTEM_PROMPT = """\
+You are OpenMythos, a powerful AI agent specialized in cybersecurity-related tasks.
+
+You have access to tools that you can use to accomplish your goals.
+
+=== IMPORTANT: How to end the conversation ===
+You MUST call the `final_message` tool when you have completed your response and want to end.
+If you do NOT call `final_message`, you will be stuck in a loop:
+  - You respond → system waits for final_message → you did not call it
+  - → system sends your response back to you → you must respond again
+  - → this repeats until you call `final_message`
+To break out of the loop, simply call `final_message` with no arguments.
+Only call `final_message` when you are done or already responded or stuck in a loop.
+"""
+
+agent = Agent(
+    base_url=os.getenv("OPENAI_BASE_URL"),
+    api_key=os.getenv("OPENAI_API_KEY"),
+    model=os.getenv("OPENAI_MODEL"),
+    system_prompt=_SYSTEM_PROMPT,
+)
+agent.register_tool(FETCH_WEBPAGE_TOOL)
+agent.register_tool(SHELL_TOOL)
+agent.register_all_mcp()
+agent.register_read_tool()
+agent.register_final_message_tool()
+
+# Load JS from external files
+_js_dir = Path(__file__).parent / "static" / "js"
+JS_LOAD_STATE = (_js_dir / "storage.load.js").read_text()
+JS_SAVE_STATE = (_js_dir / "storage.save.js").read_text()
+LANDING_PAGE_SCRIPT = (_js_dir / "landing.js").read_text()
+
+
+def _conv_choices(state_value):
+    convs = sorted(state_value["conversations"], key=lambda c: c.get("last_updated", 0), reverse=True)
+    return gr.update(
+        choices=[(c["label"], c["key"]) for c in convs],
+        value=state_value.get("conversation_id") or None,
+    )
+
+
+class GradioEvents:
+    """Event handlers for the chatbot UI."""
+
+    @staticmethod
+    def stream_response(message, state_value):
+        """Stream a chat completion into the active conversation."""
+        if not message or not message.strip():
+            yield gr.skip()
+            return
+
+        if not state_value.get("conversation_id"):
+            conv_id = str(uuid.uuid4())
+            state_value["conversation_id"] = conv_id
+            state_value["conversations"].append(
+                {"label": message[:30], "key": conv_id, "last_updated": int(time.time() * 1000)})
+            state_value["conversation_contexts"][conv_id] = {
+                "history": []
+            }
+        else:
+            conv_id = state_value["conversation_id"]
+            state_value["conversation_contexts"].setdefault(
+                conv_id, {"history": []})
+            # Update last_updated for existing conversation
+            for c in state_value["conversations"]:
+                if c["key"] == conv_id:
+                    c["last_updated"] = int(time.time() * 1000)
+                    break
+
+        ctx = state_value["conversation_contexts"][conv_id]
+
+        for c in state_value["conversations"]:
+            if c["key"] == conv_id and not c.get("label"):
+                c["label"] = message[:30]
+                break
+
+        ctx["history"].append({"role": "user", "content": message})
+
+        yield { msg: gr.update(value=""), chatbot: gr.update(value=ctx["history"]), state: gr.update(value=state_value), conv_choice: _conv_choices(state_value), send_btn: gr.update(visible=False), stop_btn: gr.update(visible=True)}
+
+        # Build display as separate titled messages (smolagents style)
+        display_messages: list[dict] = list(ctx["history"])
+        text_msg_idx: int | None = None
+        thinking_msg_idx: int | None = None
+        tool_call_idx: int | None = None
+        spinner_frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+        spinner_idx = 0
+
+        try:
+            for ev in agent.stream(ctx["history"]):
+                t = ev["type"]
+
+                if t == "reasoning":
+                    spinner_idx += 1
+                    content = f"<span class=\"thinking-indicator\">{spinner_frames[spinner_idx % len(spinner_frames)]}  Thinking...</span>"
+                    if thinking_msg_idx is not None:
+                        display_messages[thinking_msg_idx]["content"] = content
+                    else:
+                        display_messages.append({"role": "assistant", "content": content, "metadata": {}})
+                        thinking_msg_idx = len(display_messages) - 1
+
+                elif t == "text":
+                    # Remove spinner message if showing — it was a separate bubble
+                    if thinking_msg_idx is not None:
+                        display_messages.pop(thinking_msg_idx)
+                        thinking_msg_idx = None
+                        # Re-index since we popped
+                        if text_msg_idx is not None and thinking_msg_idx is not None:
+                            if  text_msg_idx > thinking_msg_idx:
+                                text_msg_idx -= 1
+
+                    if text_msg_idx is not None:
+                        display_messages[text_msg_idx]["content"] += ev["content"]
+                    else:
+                        display_messages.append({"role": "assistant", "content": ev["content"], "metadata": {}})
+                        text_msg_idx = len(display_messages) - 1
+
+                elif t == "tool_call":
+                    # Remove spinner if present
+                    if thinking_msg_idx is not None:
+                        display_messages.pop(thinking_msg_idx)
+                        if text_msg_idx is not None and text_msg_idx > thinking_msg_idx:
+                            text_msg_idx -= 1
+                        thinking_msg_idx = None
+
+                    # Finalize any in-flight text message (keep if it has real content)
+                    if text_msg_idx is not None:
+                        c = display_messages[text_msg_idx].get("content", "").strip()
+                        if not c:
+                            display_messages.pop(text_msg_idx)
+                        text_msg_idx = None
+                    tool_call_idx = None
+
+                    tool_name = ev["name"]
+                    display_messages.append({
+                        "role": "assistant",
+                        "content": f"```\n{tool_name}({ev['arguments']})\n```\n⏳ Running...",
+                        "metadata": {"title": f"🛠️ Used tool {tool_name}"},
+                    })
+                    tool_call_idx = len(display_messages) - 1
+
+                elif t == "tool_output":
+                    if tool_call_idx is not None:
+                        snippet = ev["content"][:500]
+                        cc = snippet if len(ev["content"]) <= 500 else snippet + "\n..."
+                        # Grab the tool name from the existing message
+                        tool_name = display_messages[tool_call_idx]["metadata"]["title"].split("Used tool ")[-1]
+                        display_messages[tool_call_idx]["content"] = (
+                            f"```\n{tool_name}({ev['arguments']})\n```\n\n"
+                            f"**Output:**\n```\n{cc}\n```"
+                        )
+                        display_messages[tool_call_idx]["metadata"] = {
+                            "title": f"🛠️ {tool_name} — {len(ev['content'])} chars",
+                        }
+                        # Only clear tool_call_idx if NOT partial (final output)
+                        if not ev.get("partial"):
+                            tool_call_idx = None
+
+                elif t == "error":
+                    display_messages.append({
+                        "role": "assistant",
+                        "content": f'<span style="color: var(--color-red-500)">{ev["content"]}</span>',
+                        "metadata": {"title": "💥 Error"},
+                    })
+                    yield {
+                        chatbot: gr.update(value=display_messages),
+                        state: gr.update(value=state_value),
+                        send_btn: gr.update(visible=True),
+                        stop_btn: gr.update(visible=False),
+                    }
+                    return
+
+                elif t == "done":
+                    break
+
+                yield {
+                    chatbot: gr.update(value=display_messages),
+                    state: gr.update(value=state_value),
+                }
+
+            # Sync history with display format so saves remember tool call bubbles
+            ctx["history"] = display_messages
+
+            yield {
+                chatbot: gr.update(value=ctx["history"]),
+                state: gr.update(value=state_value),
+                send_btn: gr.update(visible=True),
+                stop_btn: gr.update(visible=False),
+            }
+
+        except Exception as exc:
+            display_messages.append({
+                "role": "assistant",
+                "content": f'<span style="color: var(--color-red-400)">{exc}</span>',
+                "metadata": {"title": "💥 Error"},
+            })
+            yield {
+                chatbot: gr.update(value=display_messages),
+                state: gr.update(value=state_value),
+                send_btn: gr.update(visible=True),
+                stop_btn: gr.update(visible=False),
+            }
+
+    @staticmethod
+    def new_chat(state_value):
+        state_value["conversation_id"] = ""
+        return (
+            gr.update(value=None),
+            gr.update(value=None),
+            gr.update(value=state_value),
+        )
+
+    @staticmethod
+    def select_conversation(choice, state_value):
+        if not choice:
+            return gr.skip()
+        if choice == state_value.get("conversation_id"):
+            return gr.skip()
+
+        state_value["conversation_id"] = choice
+        ctx = state_value["conversation_contexts"].get(choice, {})
+        return (
+            gr.update(value=ctx.get("history", [])),
+            gr.update(value=state_value),
+        )
+
+    @staticmethod
+    def delete_selected_conversation(choice, state_value):
+        if not choice:
+            return gr.skip()
+
+        state_value["conversation_contexts"].pop(choice, None)
+        state_value["conversations"] = [
+            c for c in state_value["conversations"] if c["key"] != choice
+        ]
+        was_active = state_value.get("conversation_id") == choice
+        if was_active:
+            state_value["conversation_id"] = ""
+            return (
+                _conv_choices(state_value),
+                gr.update(value=None),
+                gr.update(value=state_value),
+            )
+        return (
+            _conv_choices(state_value),
+            gr.skip(),
+            gr.update(value=state_value),
+        )
+
+    @staticmethod
+    def cancel_stream(state_value):
+        """Mark the current assistant message as cancelled."""
+        if not state_value.get("conversation_id"):
+            return gr.skip()
+        ctx = state_value["conversation_contexts"][
+            state_value["conversation_id"]]
+        if ctx.get("history") and ctx["history"][-1].get("role") == "assistant":
+            ctx["history"][-1]["metadata"] = ctx["history"][-1].get(
+                "metadata", {})
+            ctx["history"][-1]["metadata"]["footer"] = "Chat completion paused"
+        return (gr.update(value=ctx.get("history", [])), gr.update(value=state_value), gr.update(visible=True), gr.update(visible=False))
+
+    @staticmethod
+    def load_from_js(serialised_json, state_value):
+        """Receive the JSON string that JS_LOAD_STATE returned, merge into state."""
+        import json
+        if not serialised_json:
+            return gr.skip(), gr.skip()
+        try:
+            loaded = json.loads(serialised_json)
+        except Exception:
+            return gr.skip(), gr.skip()
+
+        state_value["conversations"] = loaded.get("conversations", [])
+        state_value["conversation_contexts"] = loaded.get("conversation_contexts", {})
+        return _conv_choices(state_value), gr.update(value=state_value)
+
+    @staticmethod
+    def prepare_save(state_value):
+        """Serialise state to JSON so JS_SAVE_STATE can write it to localStorage."""
+        import json
+        return json.dumps({
+            "conversations": state_value.get("conversations", []),
+            "conversation_contexts": state_value.get("conversation_contexts", {}),
+        })
+
+with gr.Blocks(fill_width=True, title="Demo Chat") as demo:
+    state = gr.State({
+        "conversation_contexts": {},
+        "conversations": [],
+        "conversation_id": "",
+    })
+
+    js_load_output = gr.Textbox(visible=False, elem_id="js-load-output")
+    js_save_input  = gr.Textbox(visible=False, elem_id="js-save-input")
+
+    with gr.Row(elem_id="main-row"):
+        with gr.Sidebar(open=False):
+            new_chat_btn = gr.Button(
+                value="New Conversation",
+                variant="primary",
+            )
+            conv_choice = gr.Radio(
+                choices=[],
+                label=None,
+                interactive=True,
+                elem_id="conversations-radio",
+            )
+            delete_btn = gr.Button(
+                value="Delete Selected",
+                variant="stop",
+                visible=False
+            )
+
+        with gr.Column(elem_id="chat-column"):
+
+            # Landing page shown when chat is empty
+            landing_page = gr.HTML(
+                value="""
+                <div id="landing-page">
+                    <div class="landing-content">
+                        <div class="landing-logo">
+                            <img src="/gradio_api/file=static/svg/logo.svg" alt="MythosHarness" width="420" height="70" />
+                        </div>
+                    </div>
+                    <div class="landing-prompt">
+                        <p>Made with ❤️ by KingNish and Himanshu</p>
+                    </div>
+                </div>
+                """,
+                elem_id="landing-page-container",
+            )
+
+            chatbot = gr.Chatbot(
+                elem_id="chatbot",
+                show_label=False,
+                buttons=[],
+                layout="bubble",
+                autoscroll=False
+            )
+            with gr.Row(elem_id="input-row"):
+                msg = gr.Textbox(
+                    placeholder="Enter your message here...",
+                    show_label=False,
+                    scale=4,
+                    container=False,
+                    max_lines=10,
+                )
+                send_btn = gr.Button(
+                    "Send",
+                    variant="primary",
+                    scale=0,
+                    min_width=40,
+                    elem_id="send-btn",
+                )
+                stop_btn = gr.Button(
+                    "Stop",
+                    variant="stop",
+                    scale=0,
+                    min_width=40,
+                    visible=False,
+                    elem_id="stop-btn",
+                )
+
+    new_chat_btn.click(
+        fn=GradioEvents.new_chat,
+        inputs=[state],
+        outputs=[conv_choice, chatbot, state],
+    )
+
+    conv_choice.change(
+        fn=GradioEvents.select_conversation,
+        inputs=[conv_choice, state],
+        outputs=[chatbot, state],
+    )
+
+    delete_btn.click(
+        fn=GradioEvents.delete_selected_conversation,
+        inputs=[conv_choice, state],
+        outputs=[conv_choice, chatbot, state],
+    )
+
+    submit_event = send_btn.click(
+        fn=GradioEvents.stream_response,
+        inputs=[msg, state],
+        outputs=[msg, chatbot, state, conv_choice, send_btn, stop_btn],
+    )
+    msg.submit(
+        fn=GradioEvents.stream_response,
+        inputs=[msg, state],
+        outputs=[msg, chatbot, state, conv_choice, send_btn, stop_btn],
+    )
+
+    stop_btn.click(
+        fn=GradioEvents.cancel_stream,
+        inputs=[state],
+        outputs=[chatbot, state, send_btn, stop_btn],
+        cancels=[submit_event],
+    )
+
+    state.change(
+        fn=GradioEvents.prepare_save,
+        inputs=[state],
+        outputs=[js_save_input],
+    ).then(
+        fn=lambda x: x,
+        inputs=[js_save_input],
+        outputs=[js_save_input],
+        js=JS_SAVE_STATE,
+    )
+
+    demo.load(
+        fn=lambda: None,
+        inputs=None,
+        outputs=None,
+        js=LANDING_PAGE_SCRIPT,
+    ).then(
+        fn=lambda x: x,
+        inputs=[js_load_output],
+        outputs=[js_load_output],
+        js=JS_LOAD_STATE,
+    ).then(
+        fn=GradioEvents.load_from_js,
+        inputs=[js_load_output, state],
+        outputs=[conv_choice, state],
+    )
+
+theme = gr.themes.Base(radius_size="none")
+
+if __name__ == "__main__":
+    demo.queue(default_concurrency_limit=100, max_size=100).launch(ssr_mode=False, max_threads=100, css_paths="app.css", theme=theme)

requirements.txt

@@ -0,0 +1,6 @@
+gradio==6.8.0
+openai==2.41.0
+python-dotenv==1.2.2
+cloudscraper>=1.2,<2
+trafilatura>=2.0,<3
+markitdown>=0.1,<1

static/js/landing.js

@@ -0,0 +1,74 @@
+() => {
+    // Landing page toggle logic
+    const landingPage = document.getElementById('landing-page-container');
+    const chatbot = document.getElementById('chatbot');
+    const msgInput = document.querySelector('#input-row textarea, #input-row input[type="text"]');
+
+    if (!landingPage || !chatbot) return;
+
+    function toggleLanding() {
+        // Check if chatbot has any messages
+        const messages = chatbot.querySelectorAll('[data-testid="bot"], [data-testid="user"], [class*="message"]');
+        const hasMessages = messages.length > 0;
+
+        // Also check for empty state indicators
+        const emptyState = chatbot.querySelector('.empty-state, .placeholder, [class*="empty"]');
+        const chatColumn = document.getElementById('chat-column');
+
+        if (hasMessages && !emptyState) {
+            landingPage.classList.add('hidden');
+            if (chatColumn) chatColumn.classList.remove('landing-active');
+        } else {
+            landingPage.classList.remove('hidden');
+            if (chatColumn) chatColumn.classList.add('landing-active');
+        }
+    }
+
+    // Initial check
+    toggleLanding();
+
+    // Set up mutation observer to watch for chat changes
+    const observer = new MutationObserver((mutations) => {
+        let shouldToggle = false;
+        for (const mutation of mutations) {
+            if (mutation.type === 'childList' || mutation.type === 'subtree') {
+                shouldToggle = true;
+                break;
+            }
+        }
+        if (shouldToggle) {
+            // Debounce the toggle check
+            clearTimeout(window._landingToggleTimeout);
+            window._landingToggleTimeout = setTimeout(toggleLanding, 100);
+        }
+    });
+
+    observer.observe(chatbot, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: ['class']
+    });
+
+    // Also watch for the input area to handle new chat creation
+    const inputRow = document.getElementById('input-row');
+    if (inputRow) {
+        observer.observe(inputRow, {
+            childList: true,
+            subtree: true
+        });
+    }
+
+    // Click on landing prompt to focus input
+    const landingPrompt = document.querySelector('.landing-prompt');
+    if (landingPrompt && msgInput) {
+        landingPrompt.addEventListener('click', () => {
+            msgInput.focus();
+            msgInput.click();
+        });
+    }
+
+    // Store reference for cleanup
+    window._landingPageObserver = observer;
+    window._landingPage = landingPage;
+}

static/js/storage.load.js

@@ -0,0 +1,20 @@
+(_) => {
+    const titles = JSON.parse(localStorage.getItem("titles") || "{}");
+    const conversations = [];
+    const conversation_contexts = {};
+
+    for (const [id, data] of Object.entries(titles)) {
+        const raw = localStorage.getItem("chat_id_" + id);
+        if (raw) {
+            const label = typeof data === 'string' ? data : data.label;
+            const last_updated = typeof data === 'string' ? 0 : (data.last_updated || 0);
+            conversations.push({ key: id, label: label, last_updated: last_updated });
+            conversation_contexts[id] = JSON.parse(raw);
+        }
+    }
+
+    // Sort newest first
+    conversations.sort((a, b) => (b.last_updated || 0) - (a.last_updated || 0));
+
+    return JSON.stringify({ conversations, conversation_contexts });
+}

static/js/storage.save.js

@@ -0,0 +1,28 @@
+(stateJson) => {
+    const state = JSON.parse(stateJson);
+    const titles = {};
+
+    for (const conv of (state.conversations || [])) {
+        titles[conv.key] = { label: conv.label, last_updated: conv.last_updated || 0 };
+        const ctx = (state.conversation_contexts || {})[conv.key];
+        if (ctx !== undefined) {
+            localStorage.setItem("chat_id_" + conv.key, JSON.stringify(ctx));
+        }
+    }
+
+    // Remove stale chat_id_* keys that are no longer in conversations
+    const validIds = new Set(Object.keys(titles));
+    for (let i = 0; i < localStorage.length; i++) {
+        const k = localStorage.key(i);
+        if (k && k.startsWith("chat_id_")) {
+            const id = k.slice("chat_id_".length);
+            if (!validIds.has(id)) {
+                localStorage.removeItem(k);
+                i--;  // adjust index after removal
+            }
+        }
+    }
+
+    localStorage.setItem("titles", JSON.stringify(titles));
+    return stateJson;
+}