agent-observatory-cli 0.1.0__py3-none-any.whl

observatory/integrations/langchain.py

@@ -0,0 +1,234 @@
+"""LangChain and LangGraph callback adapter for Observatory traces."""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+try:
+    from langchain_core.callbacks import BaseCallbackHandler
+except ImportError as exc:  # pragma: no cover - depends on optional integration extra
+    raise ImportError(
+        "LangChainCallbackHandler requires the optional dependency: "
+        "pip install 'agent-observatory-cli[langchain]'"
+    ) from exc
+
+
+class LangChainCallbackHandler(BaseCallbackHandler):
+    """Capture chain, tool, retriever, and model callbacks inside one active run.
+
+    Attach an instance to a :class:`observatory.client.Run` before invoking a
+    LangChain runnable or LangGraph app. Prompt, tool input, and output content
+    are omitted unless ``capture_content=True``.
+    """
+
+    def __init__(self, *, capture_content=False, max_content_chars=1000):
+        super().__init__()
+        self.capture_content = bool(capture_content)
+        self.max_content_chars = max(1, int(max_content_chars))
+        self.run = None
+        self._spans = {}
+
+    def attach(self, run):
+        if self.run is not None:
+            raise RuntimeError("callback handler is already attached to a run")
+        if run._closed:
+            raise RuntimeError("cannot attach to a closed Observatory run")
+        self.run = run
+        return self
+
+    def _content(self, value):
+        return str(value)[:self.max_content_chars]
+
+    @staticmethod
+    def _run_key(run_id):
+        return str(run_id) if run_id is not None else None
+
+    @staticmethod
+    def _name(serialized, kwargs, fallback):
+        return str((serialized or {}).get("name") or kwargs.get("name") or fallback)
+
+    @staticmethod
+    def _model(serialized, kwargs):
+        values = [kwargs.get("invocation_params"), (serialized or {}).get("kwargs"), kwargs]
+        for mapping in values:
+            if not isinstance(mapping, Mapping):
+                continue
+            for key in ("model", "model_name", "model_id", "deployment_name"):
+                value = mapping.get(key)
+                if value:
+                    return str(value)
+        return None
+
+    def _start(self, kind, name, run_id, parent_run_id=None, attributes=None):
+        if self.run is None:
+            return None
+        parent = self._spans.get(self._run_key(parent_run_id))
+        parent_span_id = parent.span_id if parent else self.run.root.span_id
+        attrs = {"langchain.run_type": kind}
+        attrs.update(attributes or {})
+        span = self.run.span(name, attributes=attrs, parent_span_id=parent_span_id)
+        key = self._run_key(run_id)
+        if key is not None:
+            self._spans[key] = span
+        return span
+
+    def _finish(self, run_id, error=None, attributes=None):
+        span = self._spans.get(self._run_key(run_id))
+        if span is None:
+            return
+        for key, value in (attributes or {}).items():
+            span.set_attribute(key, value)
+        span.finish(error)
+
+    def _capture_output(self, span, output):
+        if self.capture_content and span is not None:
+            span.set_attribute("langchain.output", self._content(output))
+
+    def on_chain_start(self, serialized, inputs, *, run_id, parent_run_id=None,
+                       tags=None, metadata=None, **kwargs):
+        attrs = {}
+        if tags:
+            attrs["langchain.tags"] = [str(tag) for tag in tags]
+        if self.capture_content:
+            attrs["langchain.input"] = self._content(inputs)
+        self._start("chain", self._name(serialized, kwargs, "chain"),
+                    run_id, parent_run_id, attrs)
+
+    def on_chain_end(self, outputs, *, run_id, **kwargs):
+        span = self._spans.get(self._run_key(run_id))
+        self._capture_output(span, outputs)
+        self._finish(run_id)
+
+    def on_chain_error(self, error, *, run_id, **kwargs):
+        self._finish(run_id, error)
+
+    def on_tool_start(self, serialized, input_str, *, run_id, parent_run_id=None,
+                      tags=None, metadata=None, **kwargs):
+        name = self._name(serialized, kwargs, "tool")
+        attrs = {"tool.name": name}
+        if self.capture_content:
+            attrs["tool.input"] = self._content(input_str)
+        self._start("tool", f"tool.{name}", run_id, parent_run_id, attrs)
+
+    def on_tool_end(self, output, *, run_id, **kwargs):
+        span = self._spans.get(self._run_key(run_id))
+        self._capture_output(span, output)
+        self._finish(run_id)
+
+    def on_tool_error(self, error, *, run_id, **kwargs):
+        self._finish(run_id, error)
+
+    def on_retriever_start(self, serialized, query, *, run_id, parent_run_id=None,
+                           tags=None, metadata=None, **kwargs):
+        attrs = {}
+        if self.capture_content:
+            attrs["retrieval.query"] = self._content(query)
+        self._start("retriever", self._name(serialized, kwargs, "retriever.search"),
+                    run_id, parent_run_id, attrs)
+
+    def on_retriever_end(self, documents, *, run_id, **kwargs):
+        span = self._spans.get(self._run_key(run_id))
+        if span is not None:
+            span.set_attribute("retrieval.document_count", len(documents))
+        self._finish(run_id)
+
+    def on_retriever_error(self, error, *, run_id, **kwargs):
+        self._finish(run_id, error)
+
+    def on_llm_start(self, serialized, prompts, *, run_id, parent_run_id=None,
+                     tags=None, metadata=None, **kwargs):
+        attrs = {"gen_ai.operation.name": "text_completion"}
+        model = self._model(serialized, kwargs)
+        if model:
+            attrs["gen_ai.request.model"] = model
+        if self.capture_content:
+            attrs["langchain.input"] = self._content(prompts)
+        self._start("llm", "llm.call", run_id, parent_run_id, attrs)
+
+    def on_chat_model_start(self, serialized, messages, *, run_id, parent_run_id=None,
+                            tags=None, metadata=None, **kwargs):
+        attrs = {"gen_ai.operation.name": "chat"}
+        model = self._model(serialized, kwargs)
+        if model:
+            attrs["gen_ai.request.model"] = model
+        if self.capture_content:
+            attrs["langchain.input"] = self._content(messages)
+        self._start("llm", "chat.call", run_id, parent_run_id, attrs)
+
+    @staticmethod
+    def _token_usage(response):
+        generations = getattr(response, "generations", None) or []
+        totals = {"input_tokens": 0, "output_tokens": 0}
+        found = False
+        for group in generations:
+            for generation in group[:1]:
+                message = getattr(generation, "message", None)
+                usage = getattr(message, "usage_metadata", None)
+                if isinstance(usage, Mapping):
+                    for key in totals:
+                        value = usage.get(key)
+                        if isinstance(value, (int, float)) and not isinstance(value, bool) and value >= 0:
+                            totals[key] += int(value)
+                            found = True
+        if found:
+            return totals
+        output = getattr(response, "llm_output", None) or {}
+        if not isinstance(output, Mapping):
+            return {}
+        usage = output.get("token_usage") or output.get("usage") or {}
+        if not isinstance(usage, Mapping):
+            return {}
+        return {"input_tokens": usage.get("input_tokens", usage.get("prompt_tokens")),
+                "output_tokens": usage.get("output_tokens", usage.get("completion_tokens"))}
+
+    def on_llm_end(self, response, *, run_id, **kwargs):
+        span = self._spans.get(self._run_key(run_id))
+        if span is None:
+            return
+        usage = self._token_usage(response)
+        for source, target in (("input_tokens", "gen_ai.usage.input_tokens"),
+                               ("output_tokens", "gen_ai.usage.output_tokens")):
+            value = usage.get(source)
+            if isinstance(value, (int, float)) and not isinstance(value, bool) and value >= 0:
+                span.set_attribute(target, int(value))
+        if self.capture_content:
+            self._capture_output(span, response)
+        self._finish(run_id)
+
+    def on_llm_error(self, error, *, run_id, **kwargs):
+        self._finish(run_id, error)
+
+    def on_agent_action(self, action, *, run_id, **kwargs):
+        span = self._spans.get(self._run_key(run_id)) or (self.run.root if self.run else None)
+        if span is not None:
+            attrs = {"tool.name": str(getattr(action, "tool", "agent.action"))}
+            if self.capture_content:
+                attrs["tool.input"] = self._content(getattr(action, "tool_input", ""))
+            span.add_event("agent.action", attrs)
+
+    def on_agent_finish(self, finish, *, run_id, **kwargs):
+        span = self._spans.get(self._run_key(run_id)) or (self.run.root if self.run else None)
+        if span is not None:
+            span.add_event("agent.finish")
+
+    def on_custom_event(self, name, data, *, run_id=None, **kwargs):
+        span = self._spans.get(self._run_key(run_id)) or (self.run.root if self.run else None)
+        event_name = str(name)
+        if span is not None:
+            attrs = {"event.name": event_name}
+            if self.capture_content:
+                attrs["event.data"] = self._content(data)
+            span.add_event("langchain.custom", attrs)
+        if self.run is None or event_name.lower() not in {
+                "progress", "agent.progress", "langgraph.progress"}:
+            return
+        progress = data if isinstance(data, Mapping) else {}
+        stage = progress.get("stage") or progress.get("agent.progress.stage") or "agent"
+        message = progress.get("message") or ""
+        percent = progress.get("percent", progress.get("agent.progress.percent"))
+        self.run.progress(str(stage), str(message), percent)
+
+    def on_retry(self, retry_state, *, run_id, **kwargs):
+        span = self._spans.get(self._run_key(run_id))
+        if span is not None:
+            span.add_event("langchain.retry")

observatory/integrations/openai_agents.py

@@ -0,0 +1,177 @@
+"""OpenAI Agents SDK tracing exporter for Observatory."""
+from __future__ import annotations
+
+import hashlib
+import json
+from collections import OrderedDict
+from collections.abc import Mapping
+from datetime import datetime
+from typing import Any
+
+try:
+    from agents.tracing.processor_interface import TracingExporter
+except ImportError as exc:  # pragma: no cover - optional integration dependency
+    raise ImportError(
+        "OpenAIAgentsExporter requires the optional dependency: "
+        "pip install 'agent-observatory-cli[openai-agents]'"
+    ) from exc
+
+
+_SAFE_TEXT_KEYS = {"type", "name", "model", "model_name", "model_id", "provider",
+                   "agent_name", "tool_name", "handoff_name", "operation"}
+_TOKEN_KEYS = {"input_tokens", "output_tokens", "prompt_tokens", "completion_tokens",
+               "total_tokens", "cached_input_tokens", "reasoning_tokens"}
+
+
+def _stable_id(value: Any, length: int) -> str:
+    """Convert SDK IDs (which may be prefixed) to valid, stable hex IDs."""
+    return hashlib.sha256(str(value).encode("utf-8")).hexdigest()[:length]
+
+
+def _timestamp_ns(value: str | None) -> int:
+    if not value:
+        return 0
+    try:
+        return int(datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp() * 1_000_000_000)
+    except (TypeError, ValueError, OverflowError):
+        return 0
+
+
+def _safe_attributes(data: Any, span_kind: str, exported=None) -> dict[str, Any]:
+    """Pick identifying fields and token counts; omit inputs, outputs, and prompts."""
+    if exported is None:
+        exported = data.export() if callable(getattr(data, "export", None)) else {}
+    if not isinstance(exported, Mapping):
+        return {}
+    result: dict[str, Any] = {}
+
+    def visit(value: Any, prefix: str = "") -> None:
+        if not isinstance(value, Mapping):
+            return
+        for raw_key, item in value.items():
+            key = str(raw_key)
+            normalized = key.lower()
+            if isinstance(item, Mapping):
+                visit(item, f"{prefix}{key}.")
+            elif normalized in _SAFE_TEXT_KEYS and isinstance(item, (str, int, float, bool)):
+                if normalized in {"model", "model_name", "model_id"}:
+                    result.setdefault("gen_ai.request.model", item)
+                elif normalized == "provider":
+                    result["gen_ai.provider.name"] = item
+                elif normalized == "agent_name" or (normalized == "name" and span_kind == "agent"):
+                    result["gen_ai.agent.name"] = item
+                elif normalized == "name" and span_kind == "function":
+                    result["tool.name"] = item
+                elif normalized == "tool_name":
+                    result["tool.name"] = item
+                else:
+                    result[f"openai_agents.{prefix}{key}"] = item
+            elif (span_kind == "generation" and normalized in _TOKEN_KEYS and
+                  isinstance(item, (int, float)) and not isinstance(item, bool) and item >= 0):
+                token_name = {"prompt_tokens": "input_tokens", "completion_tokens": "output_tokens"}.get(normalized, normalized)
+                result[f"gen_ai.usage.{token_name}"] = int(item)
+
+    visit(exported)
+    return result
+
+
+def _bounded_content(value: Any, max_chars: int) -> str:
+    if isinstance(value, str):
+        content = value
+    else:
+        content = json.dumps(value, ensure_ascii=False, separators=(",", ":"), default=str)
+    if len(content) > max_chars:
+        return content[:max_chars] + "… [truncated]"
+    return content
+
+
+class OpenAIAgentsExporter(TracingExporter):
+    """Export OpenAI Agents SDK spans to an Observatory :class:`Client`.
+
+    Pass this exporter to the SDK's ``BatchTraceProcessor`` and register that
+    processor with ``agents.tracing.add_trace_processor``. Span input/output
+    payloads and arbitrary trace metadata are intentionally omitted.
+    """
+
+    def __init__(self, client, *, capture_content=False, max_content_chars=4000):
+        self.client = client
+        self._trace_context: OrderedDict[str, tuple[str, str | None]] = OrderedDict()
+        self.capture_content = bool(capture_content)
+        self.max_content_chars = max(1, min(100_000, int(max_content_chars)))
+
+    def export(self, items) -> None:
+        spans = []
+        for item in items:
+            if hasattr(item, "span_data"):
+                spans.append(self._span_payload(item))
+            elif hasattr(item, "trace_id") and hasattr(item, "name"):
+                trace_id = str(item.trace_id)
+                group_id = getattr(item, "group_id", None)
+                self._trace_context[trace_id] = (str(item.name or "agent.run"),
+                                                 str(group_id) if group_id else None)
+                self._trace_context.move_to_end(trace_id)
+                while len(self._trace_context) > 4096:
+                    self._trace_context.popitem(last=False)
+        if spans:
+            post_spans = getattr(self.client, "_post_spans", None)
+            if callable(post_spans):
+                post_spans(spans)
+            else:
+                self.client._post("/api/spans", {"service": self.client.service, "spans": spans})
+
+    def _span_payload(self, span):
+        raw_trace_id = str(span.trace_id)
+        raw_span_id = str(span.span_id)
+        raw_parent_id = span.parent_id
+        data = span.span_data
+        kind = getattr(data, "type", None) or type(data).__name__.removesuffix("SpanData").lower()
+        exported = data.export() if callable(getattr(data, "export", None)) else {}
+        attrs = _safe_attributes(data, str(kind), exported)
+        if self.capture_content and isinstance(exported, Mapping):
+            for field in ("input", "output"):
+                if exported.get(field) is not None:
+                    attrs[f"openai_agents.{field}"] = _bounded_content(
+                        exported[field], self.max_content_chars)
+        attrs["openai_agents.trace_id"] = raw_trace_id
+        attrs["openai_agents.span_id"] = raw_span_id
+        workflow, group_id = self._trace_context.get(raw_trace_id, ("agent.run", None))
+        attrs["openai_agents.workflow"] = workflow
+        if not raw_parent_id:
+            attrs["agent.task"] = workflow
+        if group_id:
+            attrs["session.id"] = group_id
+        error = span.error
+        status = "ERROR" if error else "OK"
+        if error:
+            attrs["exception.type"] = "OpenAIAgentsError"
+        payload = {
+            "trace_id": _stable_id(raw_trace_id, 32),
+            "span_id": _stable_id(raw_span_id, 16),
+            "parent_span_id": _stable_id(raw_parent_id, 16) if raw_parent_id else None,
+            "name": f"openai_agents.{kind}",
+            "start_unix_nano": _timestamp_ns(span.started_at),
+            "end_unix_nano": _timestamp_ns(span.ended_at),
+            "status": status,
+            "attributes": attrs,
+            "events": [],
+            "resource_attributes": self.client.resource_attributes,
+        }
+        if payload["start_unix_nano"] <= 0:
+            payload["start_unix_nano"] = payload["end_unix_nano"]
+        payload["end_unix_nano"] = max(payload["start_unix_nano"], payload["end_unix_nano"])
+        return payload
+
+
+def create_processor(client, *, capture_content=False, max_content_chars=4000,
+                     **processor_options):
+    """Create the SDK's background batching processor for this Observatory client."""
+    try:
+        from agents.tracing.processors import BatchTraceProcessor
+    except ImportError as exc:  # pragma: no cover - optional integration dependency
+        raise ImportError(
+            "create_processor requires the optional dependency: "
+            "pip install 'agent-observatory-cli[openai-agents]'"
+        ) from exc
+    exporter = OpenAIAgentsExporter(client, capture_content=capture_content,
+                                    max_content_chars=max_content_chars)
+    return BatchTraceProcessor(exporter, **processor_options)

observatory/local_activity.py

@@ -0,0 +1,207 @@
+"""Bounded, redacted activity extracted from native agent session records."""
+from __future__ import annotations
+
+import json
+import re
+import shlex
+from pathlib import Path
+
+from .findings import _safe_text, _SENSITIVE_FIELD, _TOKEN_FIELD
+
+CONTENT_LIMIT = 8000
+
+
+def safe(value, limit=CONTENT_LIMIT):
+    if isinstance(value, dict):
+        value = {str(key): "[REDACTED]" if _SENSITIVE_FIELD.search(str(key)) or _TOKEN_FIELD.search(str(key))
+                 else "[opaque payload omitted]" if str(key) in {"encrypted_content", "signature", "raw_content"} or str(key) == "data" and isinstance(child, str) and len(child) > 1000
+                 else safe(child, 2000) for key, child in list(value.items())[:60]}
+        value = json.dumps(value, ensure_ascii=False, indent=2)
+    elif isinstance(value, list):
+        value = json.dumps([safe(child, 2000) for child in value[:60]], ensure_ascii=False, indent=2)
+    text = _safe_text(value)
+    text = re.sub(r"\x1b\[[0-?]*[ -/]*[@-~]", "", text)
+    text = "".join(char for char in text if char in "\n\t" or ord(char) >= 32 and ord(char) != 127)
+    return text[:limit] + ("\n[truncated]" if len(text) > limit else "")
+
+
+def plaintext(content):
+    if isinstance(content, str):
+        return safe(content)
+    if not isinstance(content, list):
+        return ""
+    return safe("\n".join(str(block.get("text") or "") for block in content
+                         if isinstance(block, dict) and block.get("type") in {"text", "input_text", "output_text"}))
+
+
+def emit(session, row, stamp, domain, action, subject, detail="", result="observed", extra=None):
+    if not stamp:
+        return None
+    from .local_agents import identity
+    attrs = {"session.id": session.session_id, "observatory.project": session.project,
+             "observatory.data_source": "local-session-log", "agent.activity.domain": domain,
+             "agent.activity.action": action, "agent.activity.subject": safe(subject, 500),
+             "agent.activity.result": result, "agent.activity.actor": session.runtime,
+             "observatory.record_id": identity(session.source_id, row.get("ordinal") or row.get("uuid") or stamp,
+                                                domain, action, str(subject)[:500]), **(extra or {})}
+    payload = row.get("payload") or {}
+    item = payload.get("item") or {} if isinstance(payload, dict) else {}
+    span_id = None
+    if isinstance(item, dict) and item.get("type") in {"CommandExecution", "FileChange", "McpToolCall", "Extension"}:
+        span_id = identity(session.source_id, ("tool", item.get("id") or row.get("ordinal") or stamp), size=16)
+    return {"trace_id": identity(session.source_id, session.turn), "span_id": span_id,
+            "time_unix_nano": stamp, "service": session.service,
+            "severity_number": 17 if result in {"error", "failed", "denied"} else 9,
+            "severity_text": "ERROR" if result in {"error", "failed", "denied"} else "INFO",
+            "event_name": "agent.activity", "body": safe(detail) if session.capture_details else "",
+            "attributes": attrs, "resource_attributes": {"observatory.source_id": session.source_id,
+                "observatory.capture": "local-session-log"}, "scope_name": "observatory.local_agents"}
+
+
+def duration(item):
+    value = item.get("duration")
+    if isinstance(value, dict):
+        try:
+            return float(value.get("secs", 0)) * 1000 + float(value.get("nanos", 0))/1e6
+        except (ValueError, TypeError):
+            pass
+    return None
+
+
+def codex_activity(session, row, stamp):
+    payload = row.get("payload") or {}
+    if not isinstance(payload, dict):
+        return []
+    kind = row.get("type")
+    event = payload.get("type")
+    out = []
+    if kind == "token_usage_record":
+        usage = payload.get("usage") or {}
+        out.append(emit(session, row, stamp, "model", "usage", session.model or "Model not reported", usage,
+                        "reported", {"gen_ai.request.model": str(session.model or "unknown")}))
+    elif kind == "response_item" and event in {"function_call", "custom_tool_call"}:
+        name = str(payload.get("name") or "Tool")
+        args = payload.get("arguments") or payload.get("input") or ""
+        try:
+            parsed = json.loads(args) if isinstance(args, str) else args
+        except (ValueError, TypeError):
+            parsed = {}
+        session.tool_inputs[str(payload.get("call_id") or payload.get("id"))] = (name, safe(args))
+        subject = name
+        domain = "tool"
+        if isinstance(parsed, dict):
+            command = parsed.get("cmd") or parsed.get("command")
+            if command:
+                domain, subject = "shell", str(command)
+            elif parsed.get("url"):
+                domain, subject = "browser", str(parsed["url"])
+            elif parsed.get("path"):
+                domain, subject = "file", str(parsed["path"])
+        out.append(emit(session, row, stamp, domain, "call", subject if session.capture_details else name,
+                        args, "started", {"tool.name": name[:128]}))
+    elif kind == "response_item" and event in {"function_call_output", "custom_tool_call_output"}:
+        key = str(payload.get("call_id") or payload.get("id"))
+        name, _ = session.tool_inputs.get(key, ("Tool", ""))
+        out.append(emit(session, row, stamp, "tool", "result", name, payload.get("output") or "", "observed"))
+    elif kind == "event_msg" and event in {"task_started", "task_complete", "task_aborted"}:
+        action = "started" if event == "task_started" else "completed" if event == "task_complete" else "interrupted"
+        out.append(emit(session, row, stamp, "agent", action, session.project or session.runtime,
+                        {key: payload[key] for key in ("duration_ms", "time_to_first_token_ms") if key in payload}, action))
+    elif kind == "turn_context":
+        # Only selected settings, never the system instructions or environment.
+        settings = {key: payload[key] for key in ("model", "effort", "approval_policy", "sandbox_policy") if key in payload}
+        out.append(emit(session, row, stamp, "context", "settings", session.model or "Agent settings", settings))
+    elif kind == "event_msg" and event == "item_completed":
+        item = payload.get("item") or {}
+        if not isinstance(item, dict):
+            return []
+        item_type = item.get("type")
+        extra = {"observatory.item_type": item_type}
+        elapsed = duration(item)
+        if elapsed is not None:
+            extra["duration_ms"] = elapsed
+        failed = str(item.get("status", "")).lower() in {"failed", "error", "declined", "denied"}
+        result = "error" if failed else "success"
+        if item_type == "CommandExecution":
+            command = item.get("command") or []
+            command = shlex.join(map(str, command)) if isinstance(command, list) else str(command)
+            code = item.get("exit_code")
+            if isinstance(code, int):
+                extra["process.exit.code"] = code
+                if code:
+                    result = "error"
+            out.append(emit(session, row, stamp, "shell", "execute", command if session.capture_details else "Shell command",
+                {"command": command, "cwd": item.get("cwd"), "exit_code": code, "output": item.get("aggregated_output", "")}, result, extra))
+        elif item_type == "FileChange":
+            changes = item.get("changes") or {}
+            if isinstance(changes, dict):
+                for path, change in list(changes.items())[:60]:
+                    operation = change.get("type") or change.get("kind") or "change" if isinstance(change, dict) else "change"
+                    if isinstance(operation, dict):
+                        operation = next(iter(operation), "change")
+                    operation = str(operation)
+                    out.append(emit(session, row, stamp, "file", operation[:40], path if session.capture_details else Path(path).name,
+                                    change, result, extra))
+        elif item_type == "Extension":
+            action = item.get("action") or {}
+            name = str(action.get("type") or item.get("kind") or "activity") if isinstance(action, dict) else str(item.get("kind") or "activity")
+            subject = action.get("url") or item.get("query") or name if isinstance(action, dict) else name
+            out.append(emit(session, row, stamp, "browser", name, subject if session.capture_details else name,
+                {"action": action, "query": item.get("query"), "results": item.get("results")}, result, extra))
+        elif item_type == "McpToolCall":
+            name = str(item.get("tool") or "MCP tool")
+            extra["mcp.server.name"] = str(item.get("server") or "")[:128]
+            extra["mcp.tool.name"] = name
+            extra["mcp.method.name"] = "tools/call"
+            details = {"arguments": item.get("arguments"), "result": item.get("result")}
+            if isinstance(item.get("result"), dict) and item["result"].get("isError"):
+                result = "error"
+            out.append(emit(session, row, stamp, "mcp", name, str(item.get("server") or "MCP"), details, result, extra))
+        elif item_type in {"UserMessage", "AgentMessage"}:
+            text = "" if session.internal else plaintext(item.get("content"))
+            role = "user" if item_type == "UserMessage" else "assistant"
+            if role == "user" and text and session.capture_details:
+                session.tasks[session.turn] = text[:4000]
+            out.append(emit(session, row, stamp, "message", role,
+                "Approval review" if session.internal else text.splitlines()[0][:300] if text and session.capture_details else role + " message", text,
+                "observed", {"message.role": role, "message.phase": item.get("phase") or ""}))
+        elif item_type in {"Reasoning", "ContextCompaction"}:
+            out.append(emit(session, row, stamp, "agent", "processing" if item_type == "Reasoning" else "compaction",
+                            "Model processing" if item_type == "Reasoning" else "Context compacted"))
+    return [entry for entry in out if entry]
+
+
+def claude_activity(session, row, stamp):
+    message = row.get("message") or {}
+    if not isinstance(message, dict):
+        return []
+    content = message.get("content") or []
+    blocks = content if isinstance(content, list) else []
+    out = []
+    if row.get("type") == "assistant" and isinstance(message.get("usage"), dict):
+        out.append(emit(session, row, stamp, "model", "usage", session.model or "Model not reported", message["usage"], "reported"))
+    text = plaintext(content)
+    if text and row.get("type") in {"assistant", "user"}:
+        role = row["type"]
+        if role == "user" and session.capture_details:
+            session.tasks[session.turn] = text[:4000]
+        out.append(emit(session, row, stamp, "message", role, text.splitlines()[0][:300] if session.capture_details else role+" message", text))
+    for block in blocks:
+        if not isinstance(block, dict):
+            continue
+        if block.get("type") == "tool_use":
+            name, args = str(block.get("name") or "Tool"), block.get("input") or {}
+            domain = "shell" if name.lower() in {"bash", "shell", "terminal"} else "file" if name.lower() in {"read", "write", "edit", "glob", "grep", "multiedit"} else "browser" if name.lower() in {"webfetch", "websearch"} else "tool"
+            subject = args.get("command") or args.get("file_path") or args.get("path") or args.get("url") or args.get("query") or name if isinstance(args, dict) else name
+            session.tool_inputs[str(block.get("id"))] = (name, safe(subject, 500))
+            out.append(emit(session, row, stamp, domain, name, subject if session.capture_details else name, args, "started", {"tool.name": name}))
+        elif block.get("type") == "tool_result":
+            name, subject = session.tool_inputs.get(str(block.get("tool_use_id")), ("Tool", "Tool result"))
+            out.append(emit(session, row, stamp, "tool", name+" result", subject if session.capture_details else name,
+                block.get("content") or "", "error" if block.get("is_error") else "success"))
+        elif block.get("type") == "thinking":
+            out.append(emit(session, row, stamp, "agent", "processing", "Model processing"))
+    if row.get("type") == "system":
+        out.append(emit(session, row, stamp, "context", str(row.get("subtype") or "event"), "Session event",
+                        {key:row[key] for key in ("durationMs", "messageCount", "isMeta") if key in row}))
+    return [entry for entry in out if entry]