visualagents 0.1.0__py3-none-any.whl

visualagents/launcher.py

@@ -0,0 +1,87 @@
+"""Lets the dashboard start the project (the "▶ Start" button) when nothing is running yet.
+
+The agent runs in the terminal VisualAgents was started from, so it can ask its questions there.
+If the saved start command contains `{task}` (e.g. `python main.py "{task}"`), the dashboard also
+shows a box to type the task in.
+"""
+
+from __future__ import annotations
+
+import shlex
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+from . import detect, termui
+from .hub import Hub
+
+PLACEHOLDERS = ("{task}", "{prompt}")
+
+
+class Launcher:
+    def __init__(self, project: Path, hub: Hub, server_url: str, *, instrument: bool = True,
+                 fixed: detect.Candidate | None = None):
+        self.project = Path(project).resolve()
+        self.fixed = fixed  # an exact command given on the command line wins over saved / detected ones
+        self.hub = hub
+        self.server_url = server_url
+        self.instrument = instrument
+        self.thread: threading.Thread | None = None
+        self.lock = threading.Lock()
+        hub.launcher = self
+
+    def candidate(self) -> detect.Candidate | None:
+        return self.fixed or detect.load_saved(self.project) or next(iter(detect.detect(self.project)), None)
+
+    @property
+    def running(self) -> bool:
+        return self.thread is not None and self.thread.is_alive()
+
+    def info(self) -> dict[str, Any]:
+        cand = self.candidate()
+        if cand is None:
+            return {"command": None, "running": self.running,
+                    "hint": f"visualagents run {self.project} -- <the command that starts it>"}
+        return {"command": cand.label(), "running": self.running,
+                "takes_task": any(ph in tok for tok in cand.command for ph in PLACEHOLDERS)}
+
+    def start(self, task: str | None = None) -> tuple[bool, str]:
+        with self.lock:
+            if self.running or self.hub.tracker.run["status"] == "running":
+                return False, "It's already running."
+            cand = template = self.candidate()
+            if cand is None:
+                return False, "VisualAgents doesn't know how to start this project yet."
+            argv = list(cand.command)
+            if any(ph in tok for tok in argv for ph in PLACEHOLDERS):
+                if not task:
+                    return False, "Type what the agent should do first."
+                for ph in PLACEHOLDERS:
+                    argv = [tok.replace(ph, task) for tok in argv]
+                cand = detect.Candidate(argv, cand.cwd, cand.source)
+            if self.fixed is None and detect.load_saved(self.project) is None:
+                detect.save_choice(self.project, template)  # remember the command (with its {task} slot)
+            command, notes = detect.resolve(self.project, cand)
+            cwd = (self.project / cand.cwd).resolve()
+            self.thread = threading.Thread(target=self._run, args=(command, cwd, notes), name="visualagents-launch",
+                                           daemon=True)
+            self.thread.start()
+            return True, "Starting in your terminal - give it its task there."
+
+    def _run(self, command: list[str], cwd: Path, notes: list[str]) -> None:
+        from .runner import follow_new_logs, run_command
+
+        termui.info(f"Starting from the dashboard: {shlex.join(command)}")
+        for note in notes:
+            termui.info(note)
+        termui.info("The map comes alive as it works - answer its questions here in the terminal.")
+        stop = threading.Event()
+        threading.Thread(target=follow_new_logs, args=(self.project, self.hub), daemon=True,
+                         kwargs={"since": time.time() - 1, "stop": stop}).start()
+        try:
+            code = run_command(command, self.hub, cwd=cwd, server_url=self.server_url, instrument=self.instrument)
+            termui.info(f"{self.project.name} {'finished' if code == 0 else f'exited with code {code}'}. "
+                        "Press ▶ in the dashboard to run it again, or Ctrl+C here to close.")
+        finally:
+            stop.set()

visualagents/llm.py

@@ -0,0 +1,314 @@
+"""LLM access for VisualAgents: codebase -> blueprint, and (optionally) live narration.
+
+Providers (pick with --provider / --model, or VISUALAGENTS_PROVIDER / VISUALAGENTS_MODEL):
+- anthropic: Claude via the official `anthropic` SDK (installed by default)
+- openai:    OpenAI or any OpenAI-compatible server (Ollama, LM Studio, vLLM via OPENAI_BASE_URL);
+             `pip install "visualagents[openai]"`
+- google:    Gemini via the official `google-genai` SDK (GEMINI_API_KEY, or Vertex AI);
+             `pip install "visualagents[google]"`
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+PROVIDERS = ("anthropic", "openai", "google")
+# Default model for reading the codebase (quality matters) and for --smart narration (runs every few seconds).
+DEFAULT_MODELS = {"anthropic": "claude-opus-5-5", "openai": "gpt-5", "google": "gemini-pro-latest"}
+NARRATE_MODELS = {"anthropic": "claude-opus-5-5", "openai": "gpt-5", "google": "gemini-flash-lite-latest"}
+PROVIDER_LABELS = {"anthropic": "Anthropic Claude", "openai": "OpenAI / compatible", "google": "Google Gemini"}
+KEY_VARS = {
+    "anthropic": ("ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"),
+    "openai": ("OPENAI_API_KEY", "OPENAI_BASE_URL"),
+    "google": ("GEMINI_API_KEY", "GOOGLE_API_KEY", "GOOGLE_GENAI_USE_VERTEXAI"),
+}
+_DOTENV_VARS = {
+    *(v for vs in KEY_VARS.values() for v in vs), "ANTHROPIC_BASE_URL", "GOOGLE_CLOUD_PROJECT",
+    "GOOGLE_CLOUD_LOCATION", "VISUALAGENTS_PROVIDER", "VISUALAGENTS_MODEL", "VISUALAGENTS_NARRATE_MODEL",
+}
+# Models that accept the server-side refusal fallback (beta server-side-fallback-2026-07-01).
+_FALLBACK_MODELS = ("claude-opus-5-5", "claude-opus-5", "claude-fable-5-1", "claude-sonnet-5-5")
+_NO_EFFORT = ("claude-3", "claude-haiku-4", "claude-sonnet-4-5", "claude-sonnet-4-0", "claude-opus-4-0", "claude-opus-4-1")
+
+
+class LLMError(RuntimeError):
+    pass
+
+
+def load_dotenv_keys(project: Path) -> None:
+    """Pick up provider keys and model choices from the project's .env if they aren't already set."""
+    for candidate in (Path(project) / ".env", Path.cwd() / ".env"):
+        try:
+            lines = candidate.read_text(encoding="utf-8").splitlines()
+        except OSError:
+            continue
+        for line in lines:
+            line = line.strip()
+            if line.startswith("export "):
+                line = line[7:]
+            if "=" not in line or line.startswith("#"):
+                continue
+            k, v = line.split("=", 1)
+            k, v = k.strip(), v.strip().strip("'\"")
+            if k in _DOTENV_VARS and v and not os.environ.get(k):
+                os.environ[k] = v
+    from . import home
+
+    home.apply_saved()  # keys and choices saved by the setup wizard come last
+
+
+def has_credentials(provider: str) -> bool:
+    if any(os.environ.get(v) for v in KEY_VARS.get(provider, ())):
+        return True
+    # `ant auth login` stores a profile the Anthropic SDK picks up without any env var
+    return provider == "anthropic" and bool(
+        os.environ.get("ANTHROPIC_PROFILE") or (Path.home() / ".config" / "anthropic").is_dir()
+    )
+
+
+def detect_provider(preferred: str = "auto") -> str | None:
+    """--provider wins, then VISUALAGENTS_PROVIDER, then the first provider with credentials."""
+    for choice in (preferred, os.environ.get("VISUALAGENTS_PROVIDER", "")):
+        if choice and choice != "auto":
+            if choice not in PROVIDERS:
+                raise LLMError(f"unknown provider {choice!r} - use one of: {', '.join(PROVIDERS)}")
+            return choice
+    for provider in ("anthropic", "openai", "google"):
+        if any(os.environ.get(v) for v in KEY_VARS[provider]):
+            return provider
+    return "anthropic" if has_credentials("anthropic") else None
+
+
+def default_model(provider: str, purpose: str = "scan") -> str:
+    """--model is handled by callers; this is the env override or the provider's default."""
+    if purpose == "narrate":
+        return os.environ.get("VISUALAGENTS_NARRATE_MODEL") or NARRATE_MODELS.get(provider, "")
+    return os.environ.get("VISUALAGENTS_MODEL") or DEFAULT_MODELS.get(provider, "")
+
+
+def complete_json(
+    *,
+    provider: str,
+    model: str | None,
+    system: str,
+    prompt: str,
+    schema: dict[str, Any],
+    effort: str = "high",
+    max_tokens: int = 64000,
+) -> dict[str, Any]:
+    model = model or default_model(provider)
+    if provider == "anthropic":
+        return _anthropic_json(model, system, prompt, schema, effort, max_tokens)
+    if provider == "openai":
+        return _openai_json(model, system, prompt, schema)
+    if provider == "google":
+        return _google_json(model, system, prompt, schema, max_tokens)
+    raise LLMError(f"unknown provider {provider!r} - use one of: {', '.join(PROVIDERS)}")
+
+
+def _anthropic_json(model: str, system: str, prompt: str, schema: dict[str, Any], effort: str, max_tokens: int) -> dict[str, Any]:
+    try:
+        import anthropic
+    except ImportError as exc:  # pragma: no cover - anthropic is a hard dependency
+        raise LLMError("the 'anthropic' package is missing: pip install anthropic") from exc
+
+    client = anthropic.Anthropic()
+    output_config: dict[str, Any] = {"format": {"type": "json_schema", "schema": schema}}
+    if not model.startswith(_NO_EFFORT):
+        output_config["effort"] = effort
+    kwargs: dict[str, Any] = {
+        "model": model,
+        "max_tokens": max_tokens,
+        "system": system,
+        "messages": [{"role": "user", "content": prompt}],
+        "output_config": output_config,
+    }
+    try:
+        if model.startswith(_FALLBACK_MODELS):
+            with client.beta.messages.stream(
+                **kwargs, betas=["server-side-fallback-2026-07-01"], fallbacks="default"
+            ) as stream:
+                message = stream.get_final_message()
+        else:
+            with client.messages.stream(**kwargs) as stream:
+                message = stream.get_final_message()
+    except anthropic.AuthenticationError as exc:
+        raise LLMError("Anthropic rejected the credentials - set ANTHROPIC_API_KEY") from exc
+    except anthropic.NotFoundError as exc:
+        raise LLMError(f"model {model!r} not found - pass --model") from exc
+    except anthropic.RateLimitError as exc:
+        raise LLMError("Anthropic rate limit hit - try again shortly") from exc
+    except anthropic.APIStatusError as exc:
+        raise LLMError(f"Anthropic API error {exc.status_code}: {exc.message}") from exc
+    except anthropic.APIConnectionError as exc:
+        raise LLMError("could not reach the Anthropic API - check your network") from exc
+
+    if message.stop_reason == "refusal":
+        raise LLMError("the model declined this request")
+    if message.stop_reason == "max_tokens":
+        raise LLMError("the model ran out of output tokens - try a smaller --max-chars")
+    text = next((b.text for b in message.content if b.type == "text"), "")
+    try:
+        return json.loads(text)
+    except ValueError as exc:
+        raise LLMError("the model returned invalid JSON") from exc
+
+
+def _openai_json(model: str, system: str, prompt: str, schema: dict[str, Any]) -> dict[str, Any]:
+    try:
+        import openai
+    except ImportError as exc:
+        raise LLMError('OpenAI support needs: pip install "visualagents[openai]"') from exc
+
+    client = openai.OpenAI()
+    sys_prompt = (
+        f"{system}\n\nRespond with a single JSON object that matches this JSON schema exactly:\n"
+        f"{json.dumps(schema)}"
+    )
+    try:
+        resp = client.chat.completions.create(
+            model=model,
+            messages=[{"role": "system", "content": sys_prompt}, {"role": "user", "content": prompt}],
+            response_format={"type": "json_object"},
+        )
+    except openai.AuthenticationError as exc:
+        raise LLMError("OpenAI rejected the credentials - set OPENAI_API_KEY") from exc
+    except openai.NotFoundError as exc:
+        raise LLMError(f"model {model!r} not found - pass --model") from exc
+    except openai.RateLimitError as exc:
+        raise LLMError("OpenAI rate limit hit - try again shortly") from exc
+    except openai.APIStatusError as exc:
+        raise LLMError(f"OpenAI API error {exc.status_code}: {exc.message}") from exc
+    except openai.APIConnectionError as exc:
+        raise LLMError("could not reach the OpenAI-compatible endpoint") from exc
+
+    choice = resp.choices[0]
+    if getattr(choice.message, "refusal", None):
+        raise LLMError("the model declined this request")
+    try:
+        return json.loads(choice.message.content or "")
+    except ValueError as exc:
+        raise LLMError("the model returned invalid JSON") from exc
+
+
+def _google_json(model: str, system: str, prompt: str, schema: dict[str, Any], max_tokens: int) -> dict[str, Any]:
+    try:
+        from google import genai
+        from google.genai import errors, types
+    except ImportError as exc:
+        raise LLMError('Gemini support needs: pip install "visualagents[google]"') from exc
+
+    # Reads GEMINI_API_KEY / GOOGLE_API_KEY, or Vertex AI via GOOGLE_GENAI_USE_VERTEXAI + project/location.
+    # Retry rate limits and "high demand" 5xx responses with backoff, like the Anthropic/OpenAI SDKs do.
+    client = genai.Client(http_options=types.HttpOptions(retry_options=types.HttpRetryOptions(
+        attempts=4, initial_delay=2.0, max_delay=20.0, http_status_codes=[408, 429, 500, 502, 503, 504],
+    )))
+    config = types.GenerateContentConfig(
+        system_instruction=system,
+        response_mime_type="application/json",
+        response_json_schema=schema,
+        max_output_tokens=min(max_tokens, 65536),
+    )
+    try:
+        resp = client.models.generate_content(model=model, contents=prompt, config=config)
+    except errors.ClientError as exc:
+        if exc.code in (401, 403):
+            raise LLMError("Google rejected the credentials - set GEMINI_API_KEY") from exc
+        if exc.code == 404:
+            raise LLMError(f"model {model!r} not found - see `visualagents models --provider google`") from exc
+        if exc.code == 429:
+            raise LLMError("Gemini rate limit or quota hit - try again shortly") from exc
+        raise LLMError(f"Gemini API error {exc.code}: {exc.message}") from exc
+    except errors.ServerError as exc:
+        raise LLMError(f"Gemini is unavailable right now ({exc.code}: {exc.message}) - retry, or pick another "
+                       f"model with --model (see `visualagents models --provider google`)") from exc
+    except errors.APIError as exc:
+        raise LLMError(f"Gemini API error {exc.code}: {exc.message}") from exc
+    except OSError as exc:
+        raise LLMError("could not reach the Gemini API - check your network") from exc
+
+    feedback = getattr(resp, "prompt_feedback", None)
+    if feedback is not None and getattr(feedback, "block_reason", None):
+        raise LLMError("the model declined this request")
+    candidate = resp.candidates[0] if resp.candidates else None
+    finish = str(getattr(candidate, "finish_reason", "") or "")
+    if "MAX_TOKENS" in finish:
+        raise LLMError("the model ran out of output tokens - try a smaller --max-chars")
+    if any(r in finish for r in ("SAFETY", "PROHIBITED", "BLOCKLIST", "SPII", "RECITATION")):
+        raise LLMError("the model declined this request")
+    try:
+        return json.loads(resp.text or "")
+    except ValueError as exc:
+        raise LLMError("the model returned invalid JSON") from exc
+
+
+def list_models(provider: str) -> list[str]:
+    """Model ids the configured account can use (best effort; listing models is free)."""
+    try:
+        if provider == "anthropic":
+            import anthropic
+
+            return [m.id for m in anthropic.Anthropic().models.list()]
+        if provider == "openai":
+            import openai
+
+            return sorted(m.id for m in openai.OpenAI().models.list())
+        if provider == "google":
+            from google import genai
+
+            client = genai.Client()  # keep a reference: the pager needs the client open
+            out = []
+            for m in client.models.list():
+                actions = getattr(m, "supported_actions", None) or []
+                if "generateContent" in actions and "gemini" in (m.name or ""):
+                    out.append(m.name.split("/")[-1])
+            return out
+    except ImportError as exc:
+        raise LLMError(f'the {provider} SDK is not installed: pip install "visualagents[{provider}]"') from exc
+    except Exception as exc:  # each SDK has its own error types; listing is informational only
+        raise LLMError(f"could not list {provider} models: {exc}") from exc
+    raise LLMError(f"unknown provider {provider!r}")
+
+
+# -- prompts ----------------------------------------------------------------
+
+SCAN_SYSTEM = """You are the code analyst inside VisualAgents, a tool that draws a live map of multi-agent AI \
+applications. You read a project's source and return its blueprint: which agents exist, what each one does, \
+and how work flows between them. The blueprint is rendered as a node graph, and later used to recognise each \
+agent in the program's printed chain-of-thought logs.
+
+Guidelines:
+- An agent is a distinct LLM-driven worker (own prompt / role / tools) or a graph node that performs a \
+distinct reasoning step. Tools, LLM clients, routers that make no LLM call, and plain helpers are not agents; \
+list a tool under the agent that calls it.
+- A single-agent program yields one agent. Do not invent agents the code does not define.
+- ids are stable snake_case names taken from the code: LangGraph node names, CrewAI agents.yaml keys, \
+Agent(name=...) values, AutoGen agent names.
+- aliases: every string that may identify the agent in logs - node name, variable names, class name, the \
+name= value, CrewAI role text with template variables removed. Always include the name of the class (or \
+function) that actually makes the LLM calls for this agent, e.g. the class holding the OpenAI client.
+- keywords: 3-8 distinctive words or short phrases this agent's own output is likely to contain.
+- edges: handoffs / control flow (who passes work to whom). conditional=true when a router, supervisor or \
+LLM decision picks the next agent. Include loops such as critic -> writer.
+- entry: the agents that receive the user's query first. exits: the agents that produce the final answer.
+- steps: the general blueprint a typical query moves through, as 2-8 ordered phases, each naming its agents.
+- file and line: where the agent is defined (use the line numbers shown in the source). line=0 if unsure.
+- Static-analysis hints are provided; trust them for names, correct them when the code says otherwise."""
+
+NARRATE_SYSTEM = """You watch the live console output of a multi-agent AI program for VisualAgents. Given the \
+program's agents and its most recent log lines, decide which agent is working right now and describe what it \
+is doing. Use an agent id from the list, or an empty string when the log does not say. activity is a \
+present-tense phrase of at most 12 words, e.g. "Searching the web for 2024 battery benchmarks"."""
+
+NARRATE_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "agent": {"type": "string"},
+        "activity": {"type": "string"},
+    },
+    "required": ["agent", "activity"],
+    "additionalProperties": False,
+}

visualagents/narrator.py

@@ -0,0 +1,58 @@
+"""Smart mode: periodically asks an LLM which agent is working and what it is doing."""
+
+from __future__ import annotations
+
+import threading
+import time
+
+from . import llm
+from .hub import Hub
+from .patterns import clean
+
+
+class Narrator:
+    def __init__(self, hub: Hub, *, provider: str, model: str | None, interval: float = 4.0):
+        self.hub = hub
+        self.provider = provider
+        self.model = model
+        self.interval = interval
+        self.stop = threading.Event()
+        self.thread = threading.Thread(target=self._loop, name="visualagents-narrator", daemon=True)
+        self._seen = 0
+        self._failures = 0
+
+    def start(self) -> "Narrator":
+        self.thread.start()
+        return self
+
+    def _loop(self) -> None:
+        agents = "\n".join(
+            f"- {a['id']}: {a['name']} - {a['role']}" for a in self.hub.blueprint["agents"]
+        ) or "- (no agents in the blueprint)"
+        while not self.stop.wait(self.interval * (1 + min(self._failures, 5))):
+            if self.hub.lines_seen == self._seen:
+                continue
+            self._seen = self.hub.lines_seen
+            lines = [clean(x) for x in list(self.hub.recent_lines)[-40:]]
+            lines = [x for x in lines if x.strip()]
+            if not lines:
+                continue
+            active = self.hub.tracker.active or "none yet"
+            prompt = (
+                f"Agents:\n{agents}\n\nCurrently highlighted agent: {active}\n\n"
+                "Most recent log lines (oldest first):\n<log>\n" + "\n".join(lines) + "\n</log>"
+            )
+            try:
+                started = time.time()
+                result = llm.complete_json(
+                    provider=self.provider, model=self.model, system=llm.NARRATE_SYSTEM, prompt=prompt,
+                    schema=llm.NARRATE_SCHEMA, effort="low", max_tokens=4000,
+                )
+                self._failures = 0
+                self.hub.narrate(result.get("agent") or None, str(result.get("activity") or "").strip())
+                if time.time() - started > self.interval * 3:
+                    self.interval *= 1.5
+            except llm.LLMError as exc:
+                self._failures += 1
+                if self._failures in (1, 5):
+                    self.hub.system(f"Smart narration paused: {exc}")

visualagents/patterns.py

@@ -0,0 +1,81 @@
+"""Log-line patterns used to attribute chain-of-thought output to agents.
+
+Add a pattern here to teach VisualAgents a new framework's console format. Agent-switch
+patterns capture the agent in a group named ``agent``; kind patterns classify the line.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+MARKER = "@@visualagents "
+
+ANSI = re.compile(r"\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[@-Z\\-_])")
+BOX = "│┃|╭╮╰╯─━┌┐└┘├┤┬┴┼║═╔╗╚╝▏▕"
+BOX_EDGES = re.compile(f"^[\\s{re.escape(BOX)}]+|[\\s{re.escape(BOX)}]+$")
+
+
+def clean(raw: str) -> str:
+    """Strip ANSI codes, carriage-return overwrites and box-drawing borders (rich panels)."""
+    line = ANSI.sub("", raw.rstrip("\n"))
+    if "\r" in line:
+        parts = [p for p in line.split("\r") if p.strip()]
+        line = parts[-1] if parts else ""
+    line = BOX_EDGES.sub("", line)
+    return line.replace("\t", "    ")
+
+
+def strip_symbols(text: str) -> str:
+    """Drop leading emoji / pictographs so '🔧 Using Tool: x' reads as 'Using Tool: x'."""
+    i = 0
+    while i < len(text) and (text[i].isspace() or text[i] == "️" or unicodedata.category(text[i]) in {"So", "Sk", "Cf", "Cn"}):
+        i += 1
+    return text[i:]
+
+
+# (pattern, strength, kind). strength "strong": an unknown agent name creates a runtime agent;
+# "weak": only applies when the name resolves to a known agent.
+SWITCH_PATTERNS: list[tuple[re.Pattern[str], str, str]] = [
+    # CrewAI: "# Agent: Senior Researcher", rich panel "Agent: X", legacy "Working Agent: X"
+    (re.compile(r"^(?:#+\s*)?Agent(?:\s+Name)?\s*:\s*(?P<agent>.{2,80}?)\s*$"), "strong", "status"),
+    (re.compile(r"Working Agent:\s*(?P<agent>.{2,80}?)\s*$"), "strong", "status"),
+    # AutoGen 0.2: "researcher (to writer):"
+    (re.compile(r"^(?P<agent>[\w\-. ]{1,40}?)\s+\(to\s+(?P<to>[\w\-. ]{1,40})\)\s*:?\s*$"), "strong", "message"),
+    # AutoGen 0.4 console: "---------- TextMessage (researcher) ----------" / "---------- researcher ----------"
+    (re.compile(r"^-{4,}\s*(?:\w*(?:Message|Event)\s*)?\(?(?P<agent>[\w\-.]+)\)?\s*-{4,}\s*$"), "strong", "message"),
+    # LangGraph: "Update from node researcher:", message pretty_print "Name: researcher", stream dicts
+    (re.compile(r"^Update from (?:node|subgraph)\s+(?P<agent>[\w\-.]+)"), "strong", "status"),
+    (re.compile(r"^Name:\s*(?P<agent>[\w\-.]+)\s*$"), "weak", "status"),
+    (re.compile(r"""^\{\s*['"](?P<agent>[\w\-]+)['"]\s*:\s*[\{\[]"""), "weak", "status"),
+    # OpenAI Agents SDK / Swarm style
+    (re.compile(r"(?:Handoff|Handed off|Handing off|Transferr(?:ed|ing))\s+(?:control\s+)?to\s*:?\s*['\"`]?(?P<agent>[\w\- ]{2,40}?)['\"`]?(?:\s+agent)?\s*(?:[.,:!]|$)", re.I), "weak", "handoff"),
+    (re.compile(r"\btransfer_to_(?P<agent>\w+)"), "weak", "handoff"),
+    # Generic narration
+    (re.compile(r"(?:Delegating|Passing|Routing|Sending|Switching|Returning|Forwarding)\s+(?:[\w\-]+\s+){0,3}?to\s+(?:the\s+)?['\"`]?(?P<agent>[\w\- ]{2,40}?)['\"`]?(?:\s+agent)?\s*(?:[.,:!…]|$)", re.I), "weak", "handoff"),
+    (re.compile(r"(?:Next agent|Next node|next|goto|Selected agent|Speaker)\s*[:=]\s*['\"`]?(?P<agent>[\w\- ]{2,40}?)['\"`]?\s*$", re.I), "weak", "handoff"),
+    (re.compile(r"(?:Entering|Starting|Running|Invoking|Activating|Calling)\s+(?:the\s+)?(?:agent|node)\s*[:\-]?\s*['\"`]?(?P<agent>[\w\- ]{2,40}?)['\"`]?\s*(?:[.,:!…]|\.\.\.|$)", re.I), "weak", "status"),
+    (re.compile(r"^(?:=+|-{3,}|\*{3,}|#+|>+)\s*\[?(?P<agent>[A-Za-z][\w\- ]{1,40}?)\]?(?:\s+(?:agent|node))?\s*(?:=+|-{3,}|\*{3,}|#*)?\s*$", re.I), "weak", "status"),
+    (re.compile(r"^\[(?P<agent>[A-Za-z][\w\- .]{1,40})\]"), "weak", "log"),
+    (re.compile(r"^(?P<agent>[A-Za-z][\w\- ]{1,30}?)\s*(?:>|»|:|\||->)\s+\S"), "weak", "log"),
+]
+
+KIND_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(r"(Traceback \(most recent call last\)|^\w*(?:Error|Exception)\b\s*[:(]|^ERROR\b|^\[ERROR\]|\bFAILED\b)"), "error"),
+    (re.compile(r"^#*\s*(?:Thought|Thinking|Reasoning|Plan)\s*:\s*(?P<text>.*)$", re.I), "thought"),
+    (re.compile(r"^#*\s*(?:Using Tool|Tool|Action|Calling tool|Tool call|Calling)\s*:\s*`?(?P<tool>[\w\-.]+)`?(?P<text>.*)$", re.I), "tool"),
+    (re.compile(r"^Invoking:\s*`(?P<tool>[^`]+)`(?P<text>.*)$"), "tool"),
+    (re.compile(r"^\*{3,}\s*Suggested tool call.*?:\s*(?P<tool>[\w\-.]+)", re.I), "tool"),
+    (re.compile(r"^#*\s*(?:Action Input|Tool Input|Tool Args|Arguments)\s*:\s*(?P<text>.*)$", re.I), "tool_input"),
+    (re.compile(r"^#*\s*(?:Observation|Tool Output|Tool Result|Tool Response|Result)\s*:\s*(?P<text>.*)$", re.I), "observation"),
+    (re.compile(r"^#*\s*(?:Final Answer|Final Output|Final Response|Answer|Output|Response)\s*:\s*(?P<text>.*)$", re.I), "output"),
+    (re.compile(r"^#*\s*(?:Task|Assigned Task|Goal)\s*:\s*(?P<text>.*)$", re.I), "task"),
+    (re.compile(r"^>?\s*Entering new (?P<text>[\w ]+) chain", re.I), "status"),
+    (re.compile(r"^>?\s*Finished chain", re.I), "status"),
+]
+
+# Kinds whose following un-prefixed lines are a continuation (multi-line thoughts / answers).
+CONTINUES = {"thought", "output", "observation", "tool_input", "message", "task"}
+# Kinds that describe what an agent is doing, in order of how informative they are.
+ACTIVITY_KINDS = {"thought": 5, "tool": 5, "task": 4, "output": 5, "handoff": 3, "message": 3, "narration": 6,
+                  "observation": 2, "tool_input": 1, "log": 1}