feat: initial KAZE browser-use HF Space

.env.example

@@ -0,0 +1,11 @@
+# LLM via OpenRouter (same key as KENSHI — no new account needed)
+OPENROUTER_API_KEY=sk-or-...
+
+# KENSHI's /api/agent-report URL (where KAZE posts results)
+KENSHI_CALLBACK_URL=https://aigoose-kenshi.hf.space/api/agent-report
+
+# Must match KENSHI's AGENT_REPORT_SECRET env var
+KENSHI_CALLBACK_SECRET=your-agent-report-secret
+
+# Shared secret: KENSHI sends this in POST body when calling KAZE
+API_SECRET=your-random-api-secret

.pytest_cache/.gitignore

@@ -0,0 +1,2 @@
+# Created by pytest automatically.
+*

.pytest_cache/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

.pytest_cache/v/cache/lastfailed

@@ -0,0 +1 @@
+{}

.pytest_cache/v/cache/nodeids

@@ -0,0 +1,19 @@
+[
+  "tests/test_app.py::test_get_job_returns_404_for_missing_id",
+  "tests/test_app.py::test_get_job_returns_job_after_async_dispatch",
+  "tests/test_app.py::test_health_returns_ok",
+  "tests/test_app.py::test_run_async_queues_job_and_returns_job_id",
+  "tests/test_app.py::test_run_async_returns_401_on_wrong_secret",
+  "tests/test_app.py::test_run_async_returns_503_when_at_capacity",
+  "tests/test_app.py::test_run_sync_returns_401_on_wrong_secret",
+  "tests/test_app.py::test_run_sync_returns_503_when_at_capacity",
+  "tests/test_browser_agent.py::test_run_task_raises_on_non_rate_limit_error",
+  "tests/test_browser_agent.py::test_run_task_retries_with_fallback_on_429",
+  "tests/test_browser_agent.py::test_run_task_returns_result_dict",
+  "tests/test_jobs.py::test_count_running_reflects_status",
+  "tests/test_jobs.py::test_create_job_returns_kaze_prefixed_id",
+  "tests/test_jobs.py::test_get_job_after_create",
+  "tests/test_jobs.py::test_get_job_returns_none_for_missing_id",
+  "tests/test_jobs.py::test_update_job_sets_result_and_finished_at",
+  "tests/test_jobs.py::test_update_running_job_has_no_finished_at"
+]

Dockerfile

@@ -0,0 +1,31 @@
+FROM python:3.11-slim-bookworm
+
+RUN apt-get update && apt-get install -y \
+    wget gnupg ca-certificates git \
+    libnss3 libatk-bridge2.0-0 libgtk-3-0 \
+    libgbm-dev libasound2 libglib2.0-0 \
+    libx11-6 libx11-xcb1 libxcb1 libxcomposite1 \
+    libxcursor1 libxdamage1 libxext6 libxfixes3 \
+    libxi6 libxrandr2 libxrender1 libxtst6 \
+    libpango-1.0-0 libpangocairo-1.0-0 libxss1 \
+    libdrm2 libxkbcommon0 fonts-liberation \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+ENV PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
+RUN playwright install-deps chromium
+RUN playwright install chromium
+RUN chmod -R 755 /ms-playwright
+
+COPY . .
+
+RUN mkdir -p data
+
+ENV PORT=7860
+EXPOSE 7860
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,24 @@
 ---
-title: Kaze Browser
-emoji: 😻
-colorFrom: pink
-colorTo: red
+title: KAZE Browser Agent
+emoji: 🌬️
+colorFrom: blue
+colorTo: indigo
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# KAZE 風 — Browser Automation Agent
+
+KAZE is a browser automation sub-agent for KENSHI, built on [browser-use](https://github.com/browser-use/browser-use) + FastAPI.
+
+## Endpoints
+
+- `GET /health` — liveness check
+- `POST /run` — synchronous task (returns result inline)
+- `POST /run/async` — async task (returns job ID, webhooks back to KENSHI)
+- `GET /job/{job_id}` — poll job status
+
+## Usage
+
+KAZE is invoked by KENSHI via the `/browse` Telegram command. It is not intended for direct use.

app.py

@@ -0,0 +1,116 @@
+import asyncio
+import hmac
+import logging
+import os
+
+import httpx
+from contextlib import asynccontextmanager
+from fastapi import BackgroundTasks, FastAPI, HTTPException
+from pydantic import BaseModel
+
+import jobs
+from browser_agent import run_task
+
+logger = logging.getLogger(__name__)
+
+MAX_CONCURRENT = 2
+API_SECRET = os.getenv("API_SECRET", "")
+KENSHI_CALLBACK_URL = os.getenv("KENSHI_CALLBACK_URL", "")
+KENSHI_CALLBACK_SECRET = os.getenv("KENSHI_CALLBACK_SECRET", "")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    jobs.init_db()
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+class TaskRequest(BaseModel):
+    task: str
+    chat_id: str = ""
+    callback_url: str = ""
+    secret: str = ""
+
+
+def _verify(secret: str):
+    if API_SECRET and not hmac.compare_digest(secret, API_SECRET):
+        raise HTTPException(status_code=401, detail="Invalid secret")
+
+
+@app.get("/health")
+async def health():
+    return {
+        "status": "ok",
+        "model": "google/gemini-flash-1.5",
+        "jobs_running": jobs.count_running(),
+    }
+
+
+@app.post("/run")
+async def run_sync(req: TaskRequest):
+    _verify(req.secret)
+    if jobs.count_running() >= MAX_CONCURRENT:
+        raise HTTPException(status_code=503, detail="Max concurrent jobs reached. Try /run/async.")
+    job_id = jobs.create_job(req.task, req.chat_id)
+    jobs.update_job(job_id, "running")
+    try:
+        output = await run_task(req.task)
+        jobs.update_job(job_id, "done", output["result"])
+        return {"status": "done", "result": output["result"], "screenshots": [], "job_id": job_id}
+    except asyncio.TimeoutError:
+        jobs.update_job(job_id, "timeout", "Task exceeded 120s time limit")
+        return {"status": "timeout", "result": "Task exceeded 120s time limit", "screenshots": [], "job_id": job_id}
+    except Exception as e:
+        jobs.update_job(job_id, "failed", str(e))
+        return {"status": "failed", "result": str(e), "screenshots": [], "job_id": job_id}
+
+
+async def _run_async_job(job_id: str, task: str, chat_id: str, callback_url: str):
+    jobs.update_job(job_id, "running")
+    try:
+        output = await run_task(task)
+        jobs.update_job(job_id, "done", output["result"])
+        status, result = "done", output["result"]
+    except asyncio.TimeoutError:
+        jobs.update_job(job_id, "timeout", "Task exceeded 120s time limit")
+        status, result = "timeout", "Task exceeded 120s time limit"
+    except Exception as e:
+        jobs.update_job(job_id, "failed", str(e))
+        status, result = "failed", str(e)
+
+    url = callback_url or KENSHI_CALLBACK_URL
+    if url:
+        payload = {
+            "agentName": "KAZE",
+            "taskId": job_id,
+            "chatId": chat_id,
+            "result": result,
+            "status": status,
+        }
+        headers = {"X-Agent-Secret": KENSHI_CALLBACK_SECRET} if KENSHI_CALLBACK_SECRET else {}
+        async with httpx.AsyncClient() as client:
+            try:
+                await client.post(url, json=payload, headers=headers, timeout=10)
+            except Exception as e:
+                logger.error("[KAZE] Webhook failed for job %s: %s", job_id, e)
+
+
+@app.post("/run/async")
+async def run_async_endpoint(req: TaskRequest, background_tasks: BackgroundTasks):
+    _verify(req.secret)
+    if jobs.count_running() >= MAX_CONCURRENT:
+        raise HTTPException(status_code=503, detail="Max concurrent jobs reached.")
+    job_id = jobs.create_job(req.task, req.chat_id)
+    background_tasks.add_task(_run_async_job, job_id, req.task, req.chat_id, req.callback_url)
+    return {"job_id": job_id, "status": "queued"}
+
+
+@app.get("/job/{job_id}")
+async def get_job(job_id: str):
+    job = jobs.get_job(job_id)
+    if not job:
+        raise HTTPException(status_code=404, detail="Job not found")
+    return job

browser_agent.py

@@ -0,0 +1,40 @@
+import asyncio
+import os
+import re
+
+from langchain_openai import ChatOpenAI
+from browser_use import Agent
+
+_HTTP_RETRY_RE = re.compile(r'\b(429|500)\b')
+
+OPENROUTER_BASE = "https://openrouter.ai/api/v1"
+PRIMARY_MODEL = "google/gemini-flash-1.5"
+FALLBACK_MODEL = "deepseek/deepseek-chat-v3-0324:free"
+
+
+def _make_llm(model: str) -> ChatOpenAI:
+    api_key = os.getenv("OPENROUTER_API_KEY")
+    if not api_key:
+        raise EnvironmentError("OPENROUTER_API_KEY environment variable is not set")
+    return ChatOpenAI(
+        model=model,
+        api_key=api_key,
+        base_url=OPENROUTER_BASE,
+    )
+
+
+async def _execute(llm: ChatOpenAI, task: str, timeout: int) -> dict:
+    agent = Agent(task=task, llm=llm)
+    result = await asyncio.wait_for(agent.run(), timeout=timeout)
+    return {"result": str(result), "screenshots": []}
+
+
+async def run_task(task: str, timeout: int = 120) -> dict:
+    llm = _make_llm(PRIMARY_MODEL)
+    try:
+        return await _execute(llm, task, timeout)
+    except Exception as e:
+        if _HTTP_RETRY_RE.search(str(e)):
+            llm = _make_llm(FALLBACK_MODEL)
+            return await _execute(llm, task, timeout)
+        raise

jobs.py

@@ -0,0 +1,71 @@
+import sqlite3
+import uuid
+import os
+from datetime import datetime, timezone
+
+DB_PATH = os.path.join(os.path.dirname(__file__), "data", "jobs.db")
+
+
+def _conn():
+    c = sqlite3.connect(DB_PATH, check_same_thread=False)
+    c.row_factory = sqlite3.Row
+    return c
+
+
+def init_db():
+    os.makedirs(os.path.dirname(DB_PATH), exist_ok=True)
+    with _conn() as c:
+        c.execute("""
+            CREATE TABLE IF NOT EXISTS jobs (
+                id          TEXT PRIMARY KEY,
+                status      TEXT NOT NULL DEFAULT 'queued',
+                task        TEXT NOT NULL,
+                chat_id     TEXT,
+                result      TEXT,
+                created_at  TEXT NOT NULL,
+                finished_at TEXT
+            )
+        """)
+
+
+def create_job(task: str, chat_id: str) -> str:
+    job_id = f"kaze_{uuid.uuid4().hex[:8]}"
+    now = datetime.now(timezone.utc).isoformat()
+    with _conn() as c:
+        c.execute(
+            "INSERT INTO jobs (id, task, chat_id, created_at) VALUES (?, ?, ?, ?)",
+            (job_id, task, chat_id, now),
+        )
+    return job_id
+
+
+def update_job(job_id: str, status: str, result: str = None):
+    finished_at = (
+        datetime.now(timezone.utc).isoformat()
+        if status in ("done", "failed", "timeout")
+        else None
+    )
+    with _conn() as c:
+        c.execute(
+            "UPDATE jobs SET status=?, result=?, finished_at=? WHERE id=?",
+            (status, result, finished_at, job_id),
+        )
+
+
+def get_job(job_id: str) -> dict | None:
+    conn = _conn()
+    try:
+        row = conn.execute("SELECT * FROM jobs WHERE id=?", (job_id,)).fetchone()
+        return dict(row) if row else None
+    finally:
+        conn.close()
+
+
+def count_running() -> int:
+    conn = _conn()
+    try:
+        return conn.execute(
+            "SELECT COUNT(*) FROM jobs WHERE status IN ('running', 'queued')"
+        ).fetchone()[0]
+    finally:
+        conn.close()

requirements-dev.txt

@@ -0,0 +1,2 @@
+pytest>=8.0.0
+pytest-asyncio>=0.23.0

requirements.txt

@@ -0,0 +1,6 @@
+browser-use>=0.1.40,<0.3.0
+fastapi>=0.115.0
+uvicorn[standard]>=0.30.0
+httpx>=0.27.0
+python-dotenv>=1.0.0
+langchain-openai>=0.1.20

tests/test_app.py

@@ -0,0 +1,105 @@
+import os
+import pytest
+from unittest.mock import patch, AsyncMock
+
+os.environ["API_SECRET"] = "test-secret"
+os.environ["OPENROUTER_API_KEY"] = "test-key"
+os.environ["KENSHI_CALLBACK_URL"] = "http://kenshi-test/api/agent-report"
+os.environ["KENSHI_CALLBACK_SECRET"] = "callback-secret"
+
+import sys
+from unittest.mock import MagicMock
+sys.modules.setdefault('browser_use', MagicMock())
+
+import jobs
+from fastapi.testclient import TestClient
+
+
+@pytest.fixture(autouse=True)
+def isolated_db(tmp_path, monkeypatch):
+    monkeypatch.setattr(jobs, "DB_PATH", str(tmp_path / "test.db"))
+    jobs.init_db()
+
+
+@pytest.fixture
+def client():
+    from app import app
+    with TestClient(app) as c:
+        yield c
+
+
+def test_health_returns_ok(client):
+    r = client.get("/health")
+    assert r.status_code == 200
+    assert r.json()["status"] == "ok"
+    assert "jobs_running" in r.json()
+
+
+def test_run_async_returns_401_on_wrong_secret(client):
+    r = client.post("/run/async", json={
+        "task": "browse google.com", "chat_id": "123", "secret": "wrong"
+    })
+    assert r.status_code == 401
+
+
+def test_run_async_queues_job_and_returns_job_id(client):
+    with patch("app._run_async_job", new_callable=AsyncMock):
+        r = client.post("/run/async", json={
+            "task": "browse google.com", "chat_id": "123", "secret": "test-secret"
+        })
+    assert r.status_code == 200
+    data = r.json()
+    assert data["status"] == "queued"
+    assert data["job_id"].startswith("kaze_")
+
+
+def test_get_job_returns_404_for_missing_id(client):
+    r = client.get("/job/kaze_nonexistent")
+    assert r.status_code == 404
+
+
+def test_get_job_returns_job_after_async_dispatch(client):
+    with patch("app._run_async_job", new_callable=AsyncMock):
+        create = client.post("/run/async", json={
+            "task": "find prices on example.com",
+            "chat_id": "456",
+            "secret": "test-secret",
+        })
+    job_id = create.json()["job_id"]
+    r = client.get(f"/job/{job_id}")
+    assert r.status_code == 200
+    assert r.json()["task"] == "find prices on example.com"
+    assert r.json()["status"] in ("queued", "running")
+
+
+def test_run_async_returns_503_when_at_capacity(client):
+    j1 = jobs.create_job("task 1", "c1")
+    j2 = jobs.create_job("task 2", "c2")
+    jobs.update_job(j1, "running")
+    jobs.update_job(j2, "running")
+
+    r = client.post("/run/async", json={
+        "task": "overflow task", "chat_id": "789", "secret": "test-secret"
+    })
+    assert r.status_code == 503
+
+
+def test_run_sync_returns_401_on_wrong_secret(client):
+    with patch("app.run_task", new_callable=AsyncMock, return_value={"result": "ok", "screenshots": []}):
+        r = client.post("/run", json={
+            "task": "browse google.com", "chat_id": "123", "secret": "wrong"
+        })
+    assert r.status_code == 401
+
+
+def test_run_sync_returns_503_when_at_capacity(client):
+    j1 = jobs.create_job("task 1", "c1")
+    j2 = jobs.create_job("task 2", "c2")
+    jobs.update_job(j1, "running")
+    jobs.update_job(j2, "running")
+
+    with patch("app.run_task", new_callable=AsyncMock, return_value={"result": "ok", "screenshots": []}):
+        r = client.post("/run", json={
+            "task": "overflow task", "chat_id": "789", "secret": "test-secret"
+        })
+    assert r.status_code == 503

tests/test_browser_agent.py

@@ -0,0 +1,56 @@
+import sys
+from unittest.mock import MagicMock
+
+# Stub browser_use before it's imported by browser_agent (not installed locally)
+sys.modules.setdefault("browser_use", MagicMock())
+
+import pytest
+import asyncio
+from unittest.mock import patch, AsyncMock
+import os
+
+os.environ.setdefault("OPENROUTER_API_KEY", "test-key")
+
+
+@pytest.mark.asyncio
+async def test_run_task_returns_result_dict():
+    mock_agent = MagicMock()
+    mock_agent.run = AsyncMock(return_value="Found pricing: $29/mo starter")
+
+    with patch("browser_agent.Agent", return_value=mock_agent):
+        import browser_agent
+        result = await browser_agent.run_task("find pricing on example.com")
+
+    assert result["result"] == "Found pricing: $29/mo starter"
+    assert "screenshots" in result
+    assert result["screenshots"] == []
+
+
+@pytest.mark.asyncio
+async def test_run_task_retries_with_fallback_on_429():
+    call_count = 0
+
+    async def flaky_execute(llm, task, timeout):
+        nonlocal call_count
+        call_count += 1
+        if call_count == 1:
+            raise Exception("Error 429: rate limit exceeded")
+        return {"result": "fallback worked", "screenshots": []}
+
+    with patch("browser_agent._execute", side_effect=flaky_execute):
+        import browser_agent
+        result = await browser_agent.run_task("test task")
+
+    assert result["result"] == "fallback worked"
+    assert call_count == 2
+
+
+@pytest.mark.asyncio
+async def test_run_task_raises_on_non_rate_limit_error():
+    async def failing_execute(llm, task, timeout):
+        raise ValueError("unexpected error")
+
+    with patch("browser_agent._execute", side_effect=failing_execute):
+        import browser_agent
+        with pytest.raises(ValueError, match="unexpected error"):
+            await browser_agent.run_task("test task")

tests/test_jobs.py

@@ -0,0 +1,57 @@
+import pytest
+import jobs
+
+
+@pytest.fixture(autouse=True)
+def isolated_db(tmp_path, monkeypatch):
+    monkeypatch.setattr(jobs, "DB_PATH", str(tmp_path / "test.db"))
+    jobs.init_db()
+
+
+def test_create_job_returns_kaze_prefixed_id():
+    job_id = jobs.create_job("test task", "chat123")
+    assert job_id.startswith("kaze_")
+
+
+def test_get_job_after_create():
+    job_id = jobs.create_job("test task", "chat123")
+    job = jobs.get_job(job_id)
+    assert job is not None
+    assert job["task"] == "test task"
+    assert job["chat_id"] == "chat123"
+    assert job["status"] == "queued"
+    assert job["finished_at"] is None
+
+
+def test_update_job_sets_result_and_finished_at():
+    job_id = jobs.create_job("test task", "chat123")
+    jobs.update_job(job_id, "done", "found pricing: $29/mo")
+    job = jobs.get_job(job_id)
+    assert job["status"] == "done"
+    assert job["result"] == "found pricing: $29/mo"
+    assert job["finished_at"] is not None
+
+
+def test_update_running_job_has_no_finished_at():
+    job_id = jobs.create_job("test task", "chat123")
+    jobs.update_job(job_id, "running")
+    job = jobs.get_job(job_id)
+    assert job["status"] == "running"
+    assert job["finished_at"] is None
+
+
+def test_get_job_returns_none_for_missing_id():
+    assert jobs.get_job("kaze_nonexistent") is None
+
+
+def test_count_running_reflects_status():
+    # Queued jobs count toward capacity (race-condition fix)
+    j1 = jobs.create_job("task 1", "chat1")
+    j2 = jobs.create_job("task 2", "chat2")
+    assert jobs.count_running() == 2  # both queued
+    jobs.update_job(j1, "running")
+    assert jobs.count_running() == 2  # one running, one queued
+    jobs.update_job(j2, "running")
+    assert jobs.count_running() == 2  # both running
+    jobs.update_job(j1, "done", "result")
+    assert jobs.count_running() == 1  # one done, one still running