KohakuTerrarium 2.0.0.dev14__tar.gz → 2.0.0.dev16__tar.gz

{kohakuterrarium-2.0.0.dev14/src/KohakuTerrarium.egg-info → kohakuterrarium-2.0.0.dev16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: KohakuTerrarium
-Version: 2.0.0.dev14
+Version: 2.0.0.dev16
 Summary: A universal agent framework for building self-driven AI agents and multi-agent teams
 Author-email: "Shih-Ying Yeh (KohakuBlueLeaf)" <apolloyeh0123@gmail.com>
 License-Expression: LicenseRef-KohakuTerrarium-1.0

{kohakuterrarium-2.0.0.dev14 → kohakuterrarium-2.0.0.dev16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "KohakuTerrarium"
-version = "2.0.0.dev14"
+version = "2.0.0.dev16"
 description = "A universal agent framework for building self-driven AI agents and multi-agent teams"
 authors = [
     { name = "Shih-Ying Yeh (KohakuBlueLeaf)", email = "apolloyeh0123@gmail.com" },
@@ -291,7 +291,7 @@ select = ["F401", "F841"]
 [tool.briefcase]
 project_name = "KohakuTerrarium"
 bundle = "com.kohaku.terrarium"
-version = "2.0.0.dev14"
+version = "2.0.0.dev16"
 url = "https://github.com/Kohaku-Lab/KohakuTerrarium"
 # License is read from PEP 639 ``[project]`` above; Briefcase
 # 0.3.21+ no longer accepts ``license.file`` here.

{kohakuterrarium-2.0.0.dev14 → kohakuterrarium-2.0.0.dev16/src/KohakuTerrarium.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: KohakuTerrarium
-Version: 2.0.0.dev14
+Version: 2.0.0.dev16
 Summary: A universal agent framework for building self-driven AI agents and multi-agent teams
 Author-email: "Shih-Ying Yeh (KohakuBlueLeaf)" <apolloyeh0123@gmail.com>
 License-Expression: LicenseRef-KohakuTerrarium-1.0

{kohakuterrarium-2.0.0.dev14 → kohakuterrarium-2.0.0.dev16}/src/kohakuterrarium/__init__.py

@@ -16,7 +16,7 @@ from kohakuterrarium.terrarium import (
     Terrarium,
 )
 
-__version__ = "2.0.0.dev14"
+__version__ = "2.0.0.dev16"
 
 __all__ = [
     "ConnectionResult",

{kohakuterrarium-2.0.0.dev14 → kohakuterrarium-2.0.0.dev16}/src/kohakuterrarium/builtins/tools/bash.py

@@ -67,13 +67,31 @@ def _shell_override_env(shell_type: str) -> str | None:
 
 
 def _resolve_shell_executable(shell_type: str) -> str | None:
-    # Mobile profile (Android): the bundled busybox provides
-    # ``sh``-compatible behaviour for bash/sh/zsh requests.  We
-    # check this FIRST so an operator-supplied override env still
-    # wins for testing, but the default path on Android is the
-    # bundled sandbox (Android has no /bin and no PATH lookups
-    # produce useful results).
+    # Mobile profile (Android): every device since Android 1.0 ships
+    # ``/system/bin/sh`` (mksh — MirBSD Korn shell) plus toybox-backed
+    # ``/system/bin/{ls,grep,cat,find,…}``.  ``/system`` is mounted
+    # with the ``exec`` flag (unlike ``/data``) and the binaries are
+    # world-executable, so an app's subprocess can spawn them
+    # without any of the W^X / SELinux / PIE complications that
+    # block bundled busybox in the app's data dir.
+    #
+    # mksh is POSIX-compliant — every plain shell command the agent
+    # emits works; only bash-only extensions (``[[``, ``(( ))``,
+    # arrays, ``$'…'``) would break, and those are uncommon in tool
+    # use.  ``bash`` / ``sh`` / ``zsh`` requests all land on mksh
+    # here because none of those have stock-Android binaries either.
+    #
+    # The bundled-sandbox fallback below is kept for desktops that
+    # opt into the mobile profile for testing (and for any future
+    # APK that ships a proper PIE+bionic busybox).  Order:
+    #
+    #   1. ``/system/bin/sh`` (Android stock)
+    #   2. bundled ``sandbox_binary("sh")`` (when present)
+    #   3. operator override env / PATH lookup (desktop path)
     if is_mobile_profile() and shell_type in {"bash", "sh", "zsh"}:
+        system_sh = Path("/system/bin/sh")
+        if system_sh.is_file():
+            return str(system_sh)
         bundled = sandbox_binary("sh")
         if bundled is not None:
             return str(bundled)
@@ -377,19 +395,28 @@ class ShellTool(BaseTool):
         env = os.environ.copy()
         if self.config.env:
             env.update(self.config.env)
-        # Mobile profile: prepend the bundled sandbox bin dir to
-        # PATH so busybox sh can find its own applets via
-        # ``argv[0] = ls`` lookups when scripts shell out (busybox
-        # checks PATH after its internal applet table, which only
-        # matches when the symlink/binary literally exists).
-        # Without this, ``bash -c "ls"`` from inside our wrapped
-        # busybox would say "ls: not found" because Android has
-        # no /bin/ls.
+        # Mobile profile: Android has no ``/bin`` and no ``/usr/bin``,
+        # but ``/system/bin`` + ``/system/xbin`` carry the stock
+        # toybox-backed coreutils (``ls``, ``cat``, ``grep``,
+        # ``find``, ``sed``, ``awk``, ``date``, ``head``, ``tail``,
+        # …) plus the mksh shell and a few platform tools (``am``,
+        # ``pm``, ``logcat``).  Prepend both so ``sh -c "ls -la"``
+        # and the like resolve without needing a bundled busybox.
+        # The bundled sandbox bin dir is added LAST as a fallback
+        # for any applet toybox lacks (or for non-Android mobile-
+        # profile sideloads).
         if is_mobile_profile():
+            android_path_parts = []
+            for system_path in ("/system/bin", "/system/xbin"):
+                if Path(system_path).is_dir():
+                    android_path_parts.append(system_path)
             bin_dir = sandbox_bin_dir()
             if bin_dir is not None:
-                env["PATH"] = f"{bin_dir}{os.pathsep}{env.get('PATH', '')}".rstrip(
-                    os.pathsep
+                android_path_parts.append(str(bin_dir))
+            if android_path_parts:
+                existing = env.get("PATH", "")
+                env["PATH"] = os.pathsep.join(android_path_parts) + (
+                    os.pathsep + existing if existing else ""
                 )
 
         # Set working directory: context (agent-aware) > tool config > process cwd

kohakuterrarium-2.0.0.dev16/src/kohakuterrarium/builtins/tools/web_search.py

@@ -0,0 +1,238 @@
+"""
+Web search tool: search the web and return structured results.
+
+Primary backend: ``ddgs`` (DuckDuckGo Search, no API key needed).
+``ddgs`` transitively requires ``primp`` — a Rust+reqwest HTTP
+client wrapped via PyO3.  On Android the Rust runtime's tokio /
+rustls stack hard-crashes the host process at first call, so the
+Android build drops both ``ddgs`` and ``primp`` from
+``requirements.txt`` (see ``packaging/android/postcreate.py``'s
+``_ANDROID_DROP_PACKAGES``).
+
+Fallback backend: ``_search_httpx_ddg`` — pure-Python scrape of
+https://html.duckduckgo.com/html/ via :mod:`httpx` (already a
+core dep).  Same data source as ddgs, no native code, works
+everywhere httpx works.  Brittle if DuckDuckGo restyles the HTML,
+but it's the same surface ddgs itself parses.
+
+Resolution: try ddgs first; on ``ImportError`` (Android) or any
+runtime failure (transient primp crash, ddgs API changes, …)
+fall through to the httpx scraper.  If the scraper also fails,
+return a clear tool-unavailable error instead of crashing the
+agent.
+"""
+
+import asyncio
+import html as _html
+import re
+from typing import Any
+from urllib.parse import unquote
+
+import httpx
+
+from kohakuterrarium.builtins.tools.registry import register_builtin
+from kohakuterrarium.modules.tool.base import BaseTool, ExecutionMode, ToolResult
+from kohakuterrarium.utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+MAX_RESULTS = 10
+
+
+# Optional-dep imports at module scope so the in-function-import
+# lint stays clean.  ``DDGS`` resolves to the first available class
+# across ``ddgs`` (newer, primp-backed) and the legacy
+# ``duckduckgo_search`` (deprecated, no primp).  ``None`` when
+# neither is installed — Android default after we drop both via
+# ``packaging/android/postcreate.py:_ANDROID_DROP_PACKAGES``.
+DDGS: Any = None
+try:
+    from ddgs import DDGS  # type: ignore[no-redef]
+except ImportError:
+    try:
+        from duckduckgo_search import DDGS  # type: ignore[no-redef]
+    except ImportError:
+        pass
+
+
+def _has_ddg() -> bool:
+    return DDGS is not None
+
+
+@register_builtin("web_search")
+class WebSearchTool(BaseTool):
+    """Search the web and return structured results.
+
+    Uses DuckDuckGo (no API key required).
+    Install: pip install ddgs  (desktop)
+    On Android the primp-free httpx fallback ships by default.
+    """
+
+    @property
+    def tool_name(self) -> str:
+        return "web_search"
+
+    @property
+    def description(self) -> str:
+        return "Search the web and return results with titles, URLs, and snippets"
+
+    @property
+    def execution_mode(self) -> ExecutionMode:
+        return ExecutionMode.DIRECT
+
+    async def _execute(self, args: dict[str, Any], **kwargs: Any) -> ToolResult:
+        query = args.get("query", "")
+        if not query:
+            return ToolResult(error="No query provided. Usage: web_search(query='...')")
+
+        max_results = int(args.get("max_results", MAX_RESULTS))
+        region = args.get("region", "")
+
+        results: list[dict] = []
+        ddgs_error: Exception | None = None
+        if _has_ddg():
+            try:
+                results = await _search_ddg(query, max_results, region)
+            except Exception as e:  # noqa: BLE001 — fall through to httpx
+                ddgs_error = e
+                logger.warning(
+                    "ddgs search failed, falling back to httpx scraper",
+                    error=str(e),
+                )
+
+        if not results:
+            try:
+                results = await _search_httpx_ddg(query, max_results, region)
+            except Exception as e:
+                # Both backends down — return whichever error is more
+                # actionable.  The ddgs error usually carries more
+                # context (e.g. rate-limit, region rejected), the
+                # httpx error tends to be generic httpx.
+                detail = ddgs_error or e
+                return ToolResult(error=f"Search failed: {detail}")
+
+        if not results:
+            return ToolResult(output="No results found.", exit_code=0)
+
+        # Format results for LLM
+        lines = [f"Search results for: {query}\n"]
+        for i, r in enumerate(results, 1):
+            title = r.get("title", "")
+            url = r.get("href", r.get("url", ""))
+            snippet = r.get("body", r.get("snippet", ""))
+            lines.append(f"## {i}. {title}")
+            lines.append(f"URL: {url}")
+            if snippet:
+                lines.append(snippet)
+            lines.append("")
+
+        logger.info("Web search complete", query=query[:50], results=len(results))
+        return ToolResult(output="\n".join(lines), exit_code=0)
+
+
+async def _search_ddg(query: str, max_results: int, region: str) -> list[dict]:
+    """Run DuckDuckGo search via ``ddgs`` (sync library, run in executor)."""
+
+    def _do_search():
+        kwargs: dict[str, Any] = {"max_results": max_results}
+        if region:
+            kwargs["region"] = region
+        with DDGS() as ddgs:
+            return list(ddgs.text(query, **kwargs))
+
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(None, _do_search)
+
+
+# Each DDG HTML result lives inside ``<div class="result">``; the
+# title + URL live in ``<a class="result__a">…</a>`` and the snippet
+# in a sibling ``<a class="result__snippet">…</a>``.  These regexes
+# pull both per-result so we can zip them.  Robust against minor
+# HTML tweaks (extra attributes, whitespace) but obviously not
+# against a full DDG rebrand.
+_RE_DDG_TITLE = re.compile(
+    r'<a[^>]*class="result__a"[^>]*href="([^"]+)"[^>]*>(.*?)</a>',
+    re.DOTALL,
+)
+_RE_DDG_SNIPPET = re.compile(
+    r'class="result__snippet"[^>]*>(.*?)</a>',
+    re.DOTALL,
+)
+_RE_DDG_HTML_TAG = re.compile(r"<[^>]+>")
+_RE_DDG_REDIRECT = re.compile(r"^//duckduckgo\.com/l/\?(?:.*&)?uddg=([^&]+)")
+
+
+def _strip_html(text: str) -> str:
+    return _html.unescape(_RE_DDG_HTML_TAG.sub("", text)).strip()
+
+
+def _unwrap_ddg_redirect(href: str) -> str:
+    """DDG sometimes wraps result URLs in its own redirector.
+
+    The shape is ``//duckduckgo.com/l/?uddg=<url-encoded-target>&…``.
+    Pull the real target out so the agent gets a clickable URL,
+    not a tracker.  Non-redirect URLs pass through unchanged.
+    """
+    m = _RE_DDG_REDIRECT.match(href)
+    if m:
+        return unquote(m.group(1))
+    return href
+
+
+def _parse_ddg_html(body: str, max_results: int) -> list[dict]:
+    """Parse DuckDuckGo HTML response into the same shape ddgs returns.
+
+    Returns a list of ``{href, title, body}`` dicts so the formatter
+    in ``_execute`` doesn't have to fork on backend.  Caps at
+    ``max_results`` results.
+    """
+    results: list[dict] = []
+    for m in _RE_DDG_TITLE.finditer(body):
+        href = _unwrap_ddg_redirect(_html.unescape(m.group(1)))
+        title = _strip_html(m.group(2))
+        results.append({"href": href, "title": title, "body": ""})
+        if len(results) >= max_results:
+            break
+    snippets = [_strip_html(m.group(1)) for m in _RE_DDG_SNIPPET.finditer(body)]
+    for i, snip in enumerate(snippets[: len(results)]):
+        results[i]["body"] = snip
+    return results
+
+
+async def _search_httpx_ddg(
+    query: str,
+    max_results: int,
+    region: str,
+) -> list[dict]:
+    """Pure-Python DDG search via the HTML endpoint.
+
+    Used as the Android-default and as a fallback when ``ddgs``
+    fails on desktop.  Hits the same HTML interface ddgs itself
+    scrapes, but via ``httpx`` (already a core dep) so there's no
+    native primp/Rust footprint.
+
+    Caps at 30 results regardless of ``max_results`` — the HTML
+    endpoint returns ~30 per page and we don't paginate to keep
+    the failure surface tiny.
+    """
+    url = "https://html.duckduckgo.com/html/"
+    headers = {
+        # DDG's HTML endpoint serves a CAPTCHA challenge to obvious
+        # bot user-agents; a plain desktop-Chrome UA passes through.
+        "User-Agent": (
+            "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+            "(KHTML, like Gecko) Chrome/120.0 Safari/537.36"
+        ),
+        "Accept": "text/html,application/xhtml+xml",
+        "Accept-Language": "en-US,en;q=0.9",
+    }
+    payload: dict[str, str] = {"q": query, "b": "", "df": ""}
+    if region:
+        payload["kl"] = region
+
+    async with httpx.AsyncClient(
+        headers=headers, follow_redirects=True, timeout=15.0
+    ) as client:
+        resp = await client.post(url, data=payload)
+        resp.raise_for_status()
+        return _parse_ddg_html(resp.text, max_results)

kohakuterrarium-2.0.0.dev14/src/kohakuterrarium/builtins/tools/web_search.py

@@ -1,103 +0,0 @@
-"""
-Web search tool: search the web and return structured results.
-
-Uses duckduckgo-search (optional dep, no API key needed).
-"""
-
-import asyncio
-from typing import Any
-
-from kohakuterrarium.builtins.tools.registry import register_builtin
-from kohakuterrarium.modules.tool.base import BaseTool, ExecutionMode, ToolResult
-from kohakuterrarium.utils.logging import get_logger
-
-logger = get_logger(__name__)
-
-MAX_RESULTS = 10
-
-_HAS_DDG = False
-_DDG_MODULE = ""
-try:
-    from ddgs import DDGS  # noqa: F401
-
-    _HAS_DDG = True
-    _DDG_MODULE = "ddgs"
-except ImportError:
-    try:
-        from duckduckgo_search import DDGS  # noqa: F401
-
-        _HAS_DDG = True
-        _DDG_MODULE = "duckduckgo_search"
-    except ImportError:
-        pass
-
-
-@register_builtin("web_search")
-class WebSearchTool(BaseTool):
-    """Search the web and return structured results.
-
-    Uses DuckDuckGo (no API key required).
-    Install: pip install duckduckgo-search
-    """
-
-    @property
-    def tool_name(self) -> str:
-        return "web_search"
-
-    @property
-    def description(self) -> str:
-        return "Search the web and return results with titles, URLs, and snippets"
-
-    @property
-    def execution_mode(self) -> ExecutionMode:
-        return ExecutionMode.DIRECT
-
-    async def _execute(self, args: dict[str, Any], **kwargs: Any) -> ToolResult:
-        query = args.get("query", "")
-        if not query:
-            return ToolResult(error="No query provided. Usage: web_search(query='...')")
-
-        if not _HAS_DDG:
-            return ToolResult(
-                error="Web search not available. Install: pip install ddgs"
-            )
-
-        max_results = int(args.get("max_results", MAX_RESULTS))
-        region = args.get("region", "")
-
-        try:
-            results = await _search_ddg(query, max_results, region)
-        except Exception as e:
-            return ToolResult(error=f"Search failed: {e}")
-
-        if not results:
-            return ToolResult(output="No results found.", exit_code=0)
-
-        # Format results for LLM
-        lines = [f"Search results for: {query}\n"]
-        for i, r in enumerate(results, 1):
-            title = r.get("title", "")
-            url = r.get("href", r.get("url", ""))
-            snippet = r.get("body", r.get("snippet", ""))
-            lines.append(f"## {i}. {title}")
-            lines.append(f"URL: {url}")
-            if snippet:
-                lines.append(snippet)
-            lines.append("")
-
-        logger.info("Web search complete", query=query[:50], results=len(results))
-        return ToolResult(output="\n".join(lines), exit_code=0)
-
-
-async def _search_ddg(query: str, max_results: int, region: str) -> list[dict]:
-    """Run DuckDuckGo search (sync library, run in executor)."""
-
-    def _do_search():
-        kwargs: dict[str, Any] = {"max_results": max_results}
-        if region:
-            kwargs["region"] = region
-        with DDGS() as ddgs:
-            return list(ddgs.text(query, **kwargs))
-
-    loop = asyncio.get_running_loop()
-    return await loop.run_in_executor(None, _do_search)