agentprof 0.1.0__py3-none-any.whl

agentprof/analysis/heuristics.py

@@ -0,0 +1,306 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""Waste heuristics over the neutral model. Findings are hints, not verdicts.
+
+Heuristics only look at tool categories and normalised arguments, never at native tool ids.
+"""
+
+import re
+from collections.abc import Callable
+from typing import NamedTuple
+
+from agentprof.model import Finding, LlmCall, Node, NodeKind, ToolCategory, iter_nodes
+
+_MIN_REPEATED_READS = 3
+_MIN_REPEATED_COMMANDS = 3
+_MAX_FAILURE_RATE = 0.2
+_MIN_POLLING_STREAK = 5
+_MIN_SIBLINGS_FOR_COST_OUTLIER = 4
+_COST_OUTLIER_PERCENTILE = 0.9
+_REACQUIRE_WINDOW_MS = 10 * 60 * 1000
+_MIN_TOPIC_SIMILARITY = 0.6
+_MAX_MEAN_UNCACHED_PROMPT_TOKENS = 100_000
+_MIN_CACHE_HIT_RATIO = 0.5
+_MIN_CALLS_FOR_CACHE_RATIO = 3
+_WORD = re.compile(r"\w+")
+_NUMBER = re.compile(r"\d+")
+_AGENT_KINDS = (NodeKind.TURN, NodeKind.AGENT)
+
+
+class _Read(NamedTuple):
+    path: str
+    line_range: tuple[int, int] | None
+    node: Node
+
+
+def _reads(agent: Node) -> list[_Read]:
+    reads: list[_Read] = []
+    for child in agent.children:
+        tool = child.tool
+        if tool is None or tool.category is not ToolCategory.READ:
+            continue
+        if (path := tool.path) is not None:
+            reads.append(_Read(path=path, line_range=tool.line_range, node=child))
+    return reads
+
+
+def _is_category(node: Node, category: ToolCategory) -> bool:
+    return node.tool is not None and node.tool.category is category
+
+
+def _percentile(sorted_values: list[float], quantile: float) -> float:
+    """Linear-interpolation percentile (numpy's default `linear` method)."""
+    if len(sorted_values) == 1:
+        return sorted_values[0]
+    position = quantile * (len(sorted_values) - 1)
+    lower_index = int(position)
+    upper_index = min(lower_index + 1, len(sorted_values) - 1)
+    fraction = position - lower_index
+    return sorted_values[lower_index] + (sorted_values[upper_index] - sorted_values[lower_index]) * fraction
+
+
+def _overlaps(first: tuple[int, int] | None, second: tuple[int, int] | None) -> bool:
+    """Unknown line ranges mean the whole file and overlap everything."""
+    if first is None or second is None:
+        return True
+    return first[0] <= second[1] and second[0] <= first[1]
+
+
+def _check_repeated_reads(agent: Node) -> list[Finding]:
+    """W1: the same file read with overlapping line ranges at least three times within one agent."""
+    ranges_by_path: dict[str, list[tuple[int, int] | None]] = {}
+    for read in _reads(agent):
+        ranges_by_path.setdefault(read.path, []).append(read.line_range)
+    findings: list[Finding] = []
+    for path, ranges in ranges_by_path.items():
+        count = max(sum(1 for other in ranges if _overlaps(current, other)) for current in ranges)
+        if count >= _MIN_REPEATED_READS:
+            findings.append(
+                Finding(
+                    heuristic_id="W1",
+                    node_id=agent.node_id,
+                    severity="low",
+                    message=f"{path!r} read {count} times with overlapping line ranges",
+                    evidence={"path": path, "count": count},
+                )
+            )
+    return findings
+
+
+def _check_repeated_or_failed_commands(agent: Node) -> list[Finding]:
+    """W4: the same shell command at least three times, or a tool failure rate of 20 % or more."""
+    findings: list[Finding] = []
+    counts: dict[str, int] = {}
+    for child in agent.children:
+        tool = child.tool
+        if tool is None or tool.category is not ToolCategory.SHELL:
+            continue
+        if (command := tool.command) is not None:
+            counts[command] = counts.get(command, 0) + 1
+    for command, count in counts.items():
+        if count >= _MIN_REPEATED_COMMANDS:
+            findings.append(
+                Finding(
+                    heuristic_id="W4",
+                    node_id=agent.node_id,
+                    severity="medium",
+                    message=f"repeated command run {count} times: {command!r}",
+                    evidence={"command": command, "count": count},
+                )
+            )
+
+    tool_children = [child for child in agent.children if child.kind is NodeKind.TOOL]
+    if tool_children:
+        failures = sum(1 for child in tool_children if child.success is False)
+        rate = failures / len(tool_children)
+        if rate >= _MAX_FAILURE_RATE:
+            findings.append(
+                Finding(
+                    heuristic_id="W4",
+                    node_id=agent.node_id,
+                    severity="medium",
+                    message=f"tool failure rate {rate:.0%} ({failures}/{len(tool_children)})",
+                    evidence={"failure_rate": rate},
+                )
+            )
+    return findings
+
+
+def _check_polling_loops(agent: Node) -> list[Finding]:
+    """W5: at least five consecutive shell polling calls without other tool calls."""
+    streak = 0
+    for child in agent.children:
+        if not _is_category(child, ToolCategory.SHELL_POLL):
+            streak = 0
+            continue
+        streak += 1
+        if streak == _MIN_POLLING_STREAK:
+            return [
+                Finding(
+                    heuristic_id="W5",
+                    node_id=agent.node_id,
+                    severity="low",
+                    message=f"{streak} consecutive polling calls",
+                    evidence={"streak": streak},
+                )
+            ]
+    return []
+
+
+def _check_cost_outliers(parent: Node) -> list[Finding]:
+    """W7: an agent above the 90th percentile of its siblings' cost (at least four siblings, one unit)."""
+    siblings = [c for c in parent.children if c.kind is NodeKind.AGENT and c.cost_total.value is not None]
+    if len(siblings) < _MIN_SIBLINGS_FOR_COST_OUTLIER:
+        return []
+    units = {sibling.cost_total.unit for sibling in siblings}
+    if len(units) != 1:
+        return []
+    unit = units.pop()
+    threshold = _percentile(sorted(float(s.cost_total.value or 0.0) for s in siblings), _COST_OUTLIER_PERCENTILE)
+    findings: list[Finding] = []
+    for sibling in siblings:
+        cost = float(sibling.cost_total.value or 0.0)
+        if cost > threshold:
+            findings.append(
+                Finding(
+                    heuristic_id="W7",
+                    node_id=sibling.node_id,
+                    severity="medium",
+                    message=f"cost {cost:.1f} {unit} above the 90th percentile of its siblings",
+                    evidence={"cost": cost, "unit": unit, "threshold": threshold},
+                )
+            )
+    return findings
+
+
+def _check_reacquired_context(parent: Node) -> list[Finding]:
+    """W2: a child agent reads a file its parent read within the preceding 10 minutes."""
+    parent_read_ends = [
+        (read.path, read.node.end.number()) for read in _reads(parent) if read.node.end.value is not None
+    ]
+    findings: list[Finding] = []
+    for child_agent in parent.children:
+        if child_agent.kind is not NodeKind.AGENT:
+            continue
+        flagged: set[str] = set()
+        for read in _reads(child_agent):
+            if read.path in flagged or read.node.start.value is None:
+                continue
+            start = read.node.start.number()
+            if any(path == read.path and 0 <= start - end <= _REACQUIRE_WINDOW_MS for path, end in parent_read_ends):
+                flagged.add(read.path)
+                findings.append(
+                    Finding(
+                        heuristic_id="W2",
+                        node_id=child_agent.node_id,
+                        severity="low",
+                        message=f"{read.path!r} was already read by the parent agent",
+                        evidence={"path": read.path},
+                    )
+                )
+    return findings
+
+
+def _words(topic: str) -> set[str]:
+    return set(_WORD.findall(topic.lower()))
+
+
+def _numbers(topic: str) -> set[str]:
+    return set(_NUMBER.findall(topic))
+
+
+def _check_retry_chains(parent: Node) -> list[Finding]:
+    """W3: sibling agents with a word-set Jaccard topic similarity of at least 0.6, unless their numbers differ."""
+    agents = [child for child in parent.children if child.kind is NodeKind.AGENT]
+    findings: list[Finding] = []
+    for index, later in enumerate(agents):
+        later_words = _words(later.topic)
+        for earlier in agents[:index]:
+            earlier_words = _words(earlier.topic)
+            later_numbers, earlier_numbers = _numbers(later.topic), _numbers(earlier.topic)
+            if later_numbers and earlier_numbers and later_numbers != earlier_numbers:
+                continue  # numbered variants of one task ("Task 2", "Task 3") are not retries
+            union = later_words | earlier_words
+            if not union:
+                continue
+            similarity = len(later_words & earlier_words) / len(union)
+            if similarity >= _MIN_TOPIC_SIMILARITY:
+                findings.append(
+                    Finding(
+                        heuristic_id="W3",
+                        node_id=later.node_id,
+                        severity="medium",
+                        message=f"topic {similarity:.0%} similar to earlier sibling {earlier.node_id!r}",
+                        evidence={"earlier": earlier.node_id, "similarity": similarity},
+                    )
+                )
+                break
+    return findings
+
+
+def _prompt_and_cached(call: LlmCall) -> tuple[float, float] | None:
+    """Prompt size and cached part of one call, or `None` if the counts are unavailable."""
+    tokens = call.tokens
+    if (uncached := tokens.input.value) is None or (cached := tokens.cache_read.value) is None:
+        return None
+    cache_write = tokens.cache_write.value or 0
+    return float(uncached + cached + cache_write), float(cached)
+
+
+def _check_context_bloat(agent: Node) -> list[Finding]:
+    """W8: large mean uncached prompt per LLM call, or a low cache hit ratio.
+
+    Only the uncached part (`input + cache_write`) counts towards the size rule: cached tokens cost a fraction
+    of that, so a large but well-cached context is not waste.
+    """
+    measured = [pair for call in agent.llm_calls if (pair := _prompt_and_cached(call)) is not None]
+    if not measured:
+        return []
+    findings: list[Finding] = []
+    total_prompt = sum(prompt for prompt, _ in measured)
+    mean_uncached = sum(prompt - cached for prompt, cached in measured) / len(measured)
+    if mean_uncached > _MAX_MEAN_UNCACHED_PROMPT_TOKENS:
+        findings.append(
+            Finding(
+                heuristic_id="W8",
+                node_id=agent.node_id,
+                severity="medium",
+                message=f"mean uncached prompt of {mean_uncached:,.0f} tokens per LLM call",
+                evidence={"mean_uncached_prompt_tokens": mean_uncached},
+            )
+        )
+    if len(measured) >= _MIN_CALLS_FOR_CACHE_RATIO and total_prompt > 0:
+        ratio = sum(cached for _, cached in measured) / total_prompt
+        if ratio < _MIN_CACHE_HIT_RATIO:
+            findings.append(
+                Finding(
+                    heuristic_id="W8",
+                    node_id=agent.node_id,
+                    severity="low",
+                    message=f"cache hit ratio {ratio:.0%}",
+                    evidence={"cache_hit_ratio": ratio},
+                )
+            )
+    return findings
+
+
+_CHECKS: tuple[Callable[[Node], list[Finding]], ...] = (
+    _check_repeated_reads,
+    _check_reacquired_context,
+    _check_retry_chains,
+    _check_repeated_or_failed_commands,
+    _check_polling_loops,
+    _check_cost_outliers,
+    _check_context_bloat,
+)
+
+
+def find_findings(root: Node) -> list[Finding]:
+    """Run all heuristics on every turn and agent node of the tree rooted at `root`."""
+    return [
+        finding
+        for node in iter_nodes(root)
+        if node.kind in _AGENT_KINDS
+        for check in _CHECKS
+        for finding in check(node)
+    ]

agentprof/analysis/pipeline.py

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""Full analysis of one session: adapter parse, roll-ups and heuristics."""
+
+from agentprof.adapters.base import AgentAdapter, SessionRef
+from agentprof.analysis.call_context import annotate_call_context
+from agentprof.analysis.evidence_findings import find_evidence_findings
+from agentprof.analysis.execution import resolve_execution_links
+from agentprof.analysis.heuristics import find_findings
+from agentprof.analysis.rollup import roll_up
+from agentprof.model import Finding, Node, Session, iter_nodes
+
+
+def attach_findings(root: Node, findings: list[Finding]) -> None:
+    """Append each finding to the `findings` of the node it names."""
+    nodes_by_id = {node.node_id: node for node in iter_nodes(root)}
+    for finding in findings:
+        node = nodes_by_id.get(finding.node_id)
+        if node is None:
+            raise ValueError(f"finding {finding.heuristic_id} references unknown node {finding.node_id!r}")
+        node.findings.append(finding)
+
+
+def analyze(adapter: AgentAdapter, ref: SessionRef) -> Session:
+    """Parse `ref` with `adapter`, fill derived metrics, and attach waste findings."""
+    session = adapter.analyze(ref)
+    resolve_execution_links(session.root)
+    roll_up(session.root)
+    annotate_call_context(session.root)
+    attach_findings(session.root, [*find_findings(session.root), *find_evidence_findings(session.root)])
+    return session

agentprof/analysis/rollup.py

@@ -0,0 +1,196 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""Generic roll-ups over a neutral tree: tokens, time spans, cost, tool call counts and context.
+
+Adapters set only what they know; these rules fill in the rest the same way for every agent.
+"""
+
+from collections.abc import Callable
+from itertools import pairwise
+
+from agentprof.model import (
+    CostMetric,
+    LlmCall,
+    Metric,
+    Node,
+    NodeKind,
+    Provenance,
+    Tokens,
+    context_size,
+    sum_costs,
+    worst_provenance,
+)
+
+# Node kinds that own LLM calls and therefore tokens and cost; tool nodes and the session root never do.
+_WORKER_KINDS = (NodeKind.TURN, NodeKind.AGENT)
+
+
+def _sum_metrics(metrics: list[Metric]) -> Metric:
+    available = [metric for metric in metrics if metric.value is not None]
+    if not available:
+        return Metric.not_available()
+    provenance = worst_provenance(*(metric.provenance for metric in available))
+    if len(available) < len(metrics):
+        provenance = worst_provenance(provenance, Provenance.ESTIMATED)
+    return Metric(value=sum(metric.number() for metric in available), provenance=provenance)
+
+
+def sum_tokens(tokens: list[Tokens]) -> Tokens:
+    """Add token counts field by field."""
+    return Tokens(
+        input=_sum_metrics([t.input for t in tokens]),
+        output=_sum_metrics([t.output for t in tokens]),
+        cache_read=_sum_metrics([t.cache_read for t in tokens]),
+        cache_write=_sum_metrics([t.cache_write for t in tokens]),
+        cache_write_5m=_sum_metrics([t.cache_write_5m for t in tokens]),
+        cache_write_1h=_sum_metrics([t.cache_write_1h for t in tokens]),
+    )
+
+
+def _call_end(call: LlmCall) -> Metric:
+    if call.start.value is None:
+        return Metric.not_available()
+    if call.duration.value is None:
+        return Metric(value=call.start.value, provenance=worst_provenance(call.start.provenance, Provenance.ESTIMATED))
+    return Metric(
+        value=call.start.number() + call.duration.number(),
+        provenance=worst_provenance(call.start.provenance, call.duration.provenance),
+    )
+
+
+def _extreme(metrics: list[Metric], pick: Callable[..., Metric]) -> Metric:
+    available = [metric for metric in metrics if metric.value is not None]
+    if not available:
+        return Metric.not_available()
+    chosen = pick(available, key=Metric.number)
+    if len(available) < len(metrics):
+        return Metric(value=chosen.value, provenance=worst_provenance(chosen.provenance, Provenance.ESTIMATED))
+    return chosen
+
+
+def _roll_up_span(node: Node) -> None:
+    if node.start.value is None:
+        node.start = _extreme([c.start for c in node.children] + [call.start for call in node.llm_calls], min)
+    if node.end.value is None:
+        derived_end = _extreme([c.end for c in node.children] + [_call_end(call) for call in node.llm_calls], max)
+        node.end = Metric.estimated(derived_end.number()) if derived_end.value is not None else Metric.not_available()
+    if node.duration.value is None and node.start.value is not None and node.end.value is not None:
+        node.duration = Metric(
+            value=node.end.number() - node.start.number(),
+            provenance=worst_provenance(node.start.provenance, node.end.provenance),
+        )
+
+
+def _roll_up_tokens(node: Node) -> None:
+    if node.llm_calls:
+        node.tokens = sum_tokens([call.tokens for call in node.llm_calls])
+    parts = [child.tokens_total for child in node.children if child.kind in _WORKER_KINDS]
+    if node.kind in _WORKER_KINDS:
+        parts.append(node.tokens)
+    if parts:
+        node.tokens_total = sum_tokens(parts)
+
+
+def _subtract_children(node: Node) -> None:
+    """`cost_own` = known `cost_total` minus the direct agent children's totals of the same unit."""
+    total = node.cost_total
+    if total.value is None:
+        return
+    agent_costs = [child.cost_total for child in node.children if child.kind is NodeKind.AGENT]
+    subtractable = [value for cost in agent_costs if cost.unit == total.unit and (value := cost.value) is not None]
+    own = total.value - sum(subtractable)
+    if own < 0:
+        return  # children report more than the total (seen in real Copilot data): own cost is unknowable
+    exact = len(subtractable) == len(agent_costs) and total.provenance is Provenance.EXACT
+    node.cost_own = CostMetric(
+        value=own,
+        unit=total.unit,
+        provenance=Provenance.EXACT if exact else Provenance.ESTIMATED,
+        usd_per_unit=total.usd_per_unit,
+    )
+
+
+def _roll_up_cost(node: Node) -> None:
+    if node.cost_own.value is None and node.llm_calls:
+        node.cost_own = sum_costs([call.cost for call in node.llm_calls])
+    if node.cost_total.value is not None:
+        if node.cost_own.value is None:
+            _subtract_children(node)
+        return
+    parts = [child.cost_total for child in node.children if child.kind in _WORKER_KINDS]
+    if node.llm_calls:
+        parts.append(node.cost_own)
+    if parts:
+        node.cost_total = sum_costs(parts)
+
+
+# A call whose context is smaller than this share of the previous call's marks a compaction.
+_COMPACTION_DROP = 0.5
+
+
+def _sized_calls(calls: list[LlmCall]) -> list[tuple[LlmCall, Metric]]:
+    """Calls in the agent's context with a start and a known context size, in time order."""
+    sized: list[tuple[LlmCall, Metric]] = []
+    for call in calls:
+        size = context_size(call.tokens)
+        if call.in_context and call.start.value is not None and size.value is not None:
+            sized.append((call, size))
+    return sorted(sized, key=lambda item: item[0].start.number())
+
+
+def _drops(sized: list[tuple[LlmCall, Metric]]) -> list[LlmCall]:
+    """Calls whose context is below `_COMPACTION_DROP` of the previous call's: the first call after a compaction."""
+    return [
+        later for (_, before), (later, after) in pairwise(sized) if after.number() < before.number() * _COMPACTION_DROP
+    ]
+
+
+def _roll_up_main_agent_context(session: Node) -> None:
+    """The main agent's context runs through all turns, so a compaction may take effect at a turn boundary.
+
+    The session node reports the whole context: the largest peak and every compaction of its turns.
+    Its calls stay on the turns, so tokens and cost are not counted twice.
+    """
+    turns = [child for child in session.children if child.kind is NodeKind.TURN]
+    owners = {id(call): turn for turn in turns for call in turn.llm_calls}
+    recorded = {id(turn) for turn in turns if turn.compactions}
+    for later in _drops(_sized_calls([call for turn in turns for call in turn.llm_calls])):
+        turn = owners[id(later)]
+        if id(turn) not in recorded:
+            turn.compactions.append(Metric.estimated(later.start.number()))
+    peaks = [turn.context_peak for turn in turns if turn.context_peak.value is not None]
+    if peaks:
+        session.context_peak = max(peaks, key=Metric.number)
+    session.compactions = sorted(
+        (compaction for turn in turns for compaction in turn.compactions if compaction.value is not None),
+        key=Metric.number,
+    )
+
+
+def _roll_up_context(node: Node) -> None:
+    """Context peak over a node's own calls; compactions detected unless the adapter recorded them.
+
+    Sub-agents own their whole context; the main agent's context spans all turns and is checked on the session.
+    """
+    if node.kind is NodeKind.SESSION:
+        _roll_up_main_agent_context(node)
+        return
+    if node.kind not in _WORKER_KINDS:
+        return
+    sized = _sized_calls(node.llm_calls)
+    if not sized:
+        return
+    node.context_peak = max((size for _, size in sized), key=Metric.number)
+    if node.kind is NodeKind.AGENT and not node.compactions:
+        node.compactions = [Metric.estimated(later.start.number()) for later in _drops(sized)]
+
+
+def roll_up(node: Node) -> None:
+    """Fill derived metrics bottom-up, following the design spec's "Roll-ups" section."""
+    for child in node.children:
+        roll_up(child)
+    node.tool_call_count = Metric.exact(len(node.children))
+    _roll_up_tokens(node)
+    _roll_up_span(node)
+    _roll_up_cost(node)
+    _roll_up_context(node)

agentprof/cli.py

@@ -0,0 +1,141 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 epicodic
+"""The `agentprof` command: start the registry and the local server, and open the browser."""
+
+import argparse
+import contextlib
+import ipaddress
+import socket
+import sys
+import webbrowser
+from collections.abc import Callable
+from pathlib import Path
+from types import FrameType
+from urllib.parse import quote
+
+import uvicorn
+from fastapi import FastAPI
+
+from agentprof.adapters import load_adapters
+from agentprof.adapters.base import AdapterConfig
+from agentprof.pricing import PriceTable
+from agentprof.registry import Registry
+from agentprof.server.app import create_app
+
+_DEFAULT_HOST = "127.0.0.1"
+_DEFAULT_PORT = 8765
+_WILDCARD_HOSTS = ("0.0.0.0", "::")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="agentprof", description="Analyse AI coding agent sessions in the browser.")
+    parser.add_argument("session", nargs="?", help="session id ('<agent>:<id>' or a bare id) or session file to open")
+    parser.add_argument("--host", default=_DEFAULT_HOST, help="interface to bind (default: %(default)s)")
+    parser.add_argument("--port", type=int, default=_DEFAULT_PORT, help="port to bind (default: %(default)s)")
+    parser.add_argument("--no-browser", action="store_true", help="do not open a browser")
+    parser.add_argument("--copilot-root", type=Path, help="VS Code workspaceStorage directory")
+    parser.add_argument("--claude-root", type=Path, help="Claude Code projects directory")
+    parser.add_argument("--codex-root", type=Path, help="Codex CLI sessions directory")
+    parser.add_argument("--pricing", type=Path, help="JSON price table replacing the bundled one")
+    return parser
+
+
+def adapter_config(args: argparse.Namespace) -> AdapterConfig:
+    roots: dict[str, Path] = {}
+    if args.copilot_root is not None:
+        roots["copilot-vscode"] = args.copilot_root
+    if args.claude_root is not None:
+        roots["claude-code"] = args.claude_root
+    if args.codex_root is not None:
+        roots["codex"] = args.codex_root
+    return AdapterConfig(roots=roots, pricing_file=args.pricing)
+
+
+def is_loopback(host: str) -> bool:
+    if host == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+def browser_url(host: str, port: int, session_id: str | None) -> str:
+    shown_host = "localhost" if host in _WILDCARD_HOSTS else host
+    base = f"http://{shown_host}:{port}/"
+    return f"{base}sessions/{quote(session_id, safe='')}" if session_id is not None else base
+
+
+class _Server(uvicorn.Server):
+    """A server that calls `on_started` once it accepts connections and ends open event streams on the first Ctrl+C.
+
+    Without the latter, the shutdown would wait for the browser to disconnect.
+    """
+
+    def __init__(self, config: uvicorn.Config, end_streams: Callable[[], None], on_started: Callable[[], None]) -> None:
+        super().__init__(config)
+        self._end_streams = end_streams
+        self._on_started = on_started
+
+    async def startup(self, sockets: list[socket.socket] | None = None) -> None:
+        await super().startup(sockets)
+        if not self.should_exit:
+            self._on_started()
+
+    def handle_exit(self, sig: int, frame: FrameType | None) -> None:
+        self._end_streams()
+        super().handle_exit(sig, frame)
+
+
+def _serve(app: FastAPI, host: str, port: int, on_started: Callable[[], None]) -> None:
+    config = uvicorn.Config(app, host=host, port=port, log_level="warning")
+    with contextlib.suppress(KeyboardInterrupt):  # uvicorn re-raises the signal that stopped it, as `uvicorn.run` does
+        _Server(config, app.state.end_streams, on_started).run()
+
+
+def main(
+    argv: list[str] | None = None,
+    *,
+    serve: Callable[[FastAPI, str, int, Callable[[], None]], None] = _serve,
+    open_browser: Callable[[str], object] = webbrowser.open,
+) -> int:
+    """Run agentprof until interrupted; returns the process exit code."""
+    args = build_parser().parse_args(argv)
+    try:
+        registry = Registry(load_adapters(adapter_config(args)))
+        pricing = PriceTable.load(args.pricing)
+    except (OSError, ValueError) as error:  # e.g. an unreadable or invalid --pricing file
+        print(f"error: {error}", file=sys.stderr)
+        return 2
+    registry.refresh()
+
+    session_id: str | None = None
+    if args.session is not None:
+        try:
+            session_id = registry.resolve(args.session)
+        except LookupError as error:
+            print(f"error: {error}", file=sys.stderr)
+            return 2
+
+    if not is_loopback(args.host):
+        print(
+            f"warning: serving on {args.host} without authentication; anyone who can reach it can read your sessions",
+            file=sys.stderr,
+        )
+    url = browser_url(args.host, args.port, session_id)
+
+    def _on_started() -> None:
+        if not args.no_browser:
+            open_browser(url)
+
+    app = create_app(registry, pricing=pricing)
+    print(f"agentprof: {url}", flush=True)
+    registry.start()
+    try:
+        serve(app, args.host, args.port, _on_started)
+    except OSError as error:  # e.g. the port is already in use
+        print(f"error: cannot serve on {args.host}:{args.port}: {error}", file=sys.stderr)
+        return 2
+    finally:
+        registry.stop()
+    return 0