mcpsignals 2.0.2__tar.gz → 2.2.0__tar.gz

{mcpsignals-2.0.2 → mcpsignals-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcpsignals
-Version: 2.0.2
+Version: 2.2.0
 Summary: Drop-in instrumentation for MCP servers. Writes tool-call events to a database you own.
 Project-URL: Homepage, https://github.com/zentered-studios/mcpsignals#readme
 Project-URL: Repository, https://github.com/zentered-studios/mcpsignals
@@ -63,8 +63,10 @@ on every request, so calling it before or after your `@server.tool()`
 definitions makes no difference. The Node.js package differs here: it wraps
 `registerTool`, so it has to run before any tool is registered.
 
-With no sink configured it writes JSON lines to stdout. To write to your
-own warehouse instead:
+With no sink configured it writes JSON lines to stdout. On a stdio
+transport pass `sinks=[ConsoleSink(stream=sys.stderr)]`, because the MCP
+spec reserves stdout for protocol messages. To write to your own warehouse
+instead:
 
 ```python
 from mcpsignals import instrument
@@ -80,6 +82,56 @@ Off by default: no tool arguments are recorded unless you opt in with
 value types** are recorded, never values. See the root README's redaction
 section before enabling this in anything handling real user data.
 
+## Request-scoped runtimes and manual flushing
+
+`instrument()` returns the server unchanged. `handle_for(server)` returns an
+`InstrumentHandle` with two coroutines: `flush()` delivers everything
+buffered so far to every sink, and `close()` does a final flush, cancels the
+interval task, and unregisters the `atexit` hook. The handle is held in a
+weak registry keyed by the exact server object, so it lives as long as the
+server does; `handle_for()` returns `None` for a server that never went
+through `instrument()`.
+
+On a long-lived process, ignore the handle: the interval task and the
+`atexit` hook flush for you. Neither is reliable on a request-scoped host
+(a serverless function, or a server built fresh per request): the process
+can be frozen or discarded right after the response is sent, and `atexit`
+does not correspond to "this invocation is ending".
+
+Pass `flush_interval_s=None` for manual mode. The buffer then skips both the
+interval task and the `atexit` hook, so the host owns every flush:
+
+```python
+from mcp.server.mcpserver import MCPServer
+from mcpsignals import handle_for, instrument
+
+
+async def handle_request(request):
+    server = MCPServer("my-server")
+    instrument(
+        server,
+        server_name="my-server",
+        sinks=[...],
+        flush_interval_s=None,  # manual mode: the host flushes explicitly
+    )
+
+    @server.tool()
+    def search(query: str) -> str:
+        return f"results for {query}"
+
+    response = await serve(request, server)
+
+    await handle_for(server).flush()  # before returning the response
+    return response
+```
+
+Call `close()` instead of `flush()` when the server is done for good: at the
+end of a test, or when a per-request server is discarded. In the default
+interval mode, `close()` is also what stops the interval task and removes the
+`atexit` hook, so a test suite that instruments many servers does not
+accumulate either. Both `flush()` and `close()` are safe to await more than
+once.
+
 ## Known limitation: `session_id`
 
 `mcp` 2.0.0's middleware-facing `ServerRequestContext` does not publicly

{mcpsignals-2.0.2 → mcpsignals-2.2.0}/README.md

@@ -37,8 +37,10 @@ on every request, so calling it before or after your `@server.tool()`
 definitions makes no difference. The Node.js package differs here: it wraps
 `registerTool`, so it has to run before any tool is registered.
 
-With no sink configured it writes JSON lines to stdout. To write to your
-own warehouse instead:
+With no sink configured it writes JSON lines to stdout. On a stdio
+transport pass `sinks=[ConsoleSink(stream=sys.stderr)]`, because the MCP
+spec reserves stdout for protocol messages. To write to your own warehouse
+instead:
 
 ```python
 from mcpsignals import instrument
@@ -54,6 +56,56 @@ Off by default: no tool arguments are recorded unless you opt in with
 value types** are recorded, never values. See the root README's redaction
 section before enabling this in anything handling real user data.
 
+## Request-scoped runtimes and manual flushing
+
+`instrument()` returns the server unchanged. `handle_for(server)` returns an
+`InstrumentHandle` with two coroutines: `flush()` delivers everything
+buffered so far to every sink, and `close()` does a final flush, cancels the
+interval task, and unregisters the `atexit` hook. The handle is held in a
+weak registry keyed by the exact server object, so it lives as long as the
+server does; `handle_for()` returns `None` for a server that never went
+through `instrument()`.
+
+On a long-lived process, ignore the handle: the interval task and the
+`atexit` hook flush for you. Neither is reliable on a request-scoped host
+(a serverless function, or a server built fresh per request): the process
+can be frozen or discarded right after the response is sent, and `atexit`
+does not correspond to "this invocation is ending".
+
+Pass `flush_interval_s=None` for manual mode. The buffer then skips both the
+interval task and the `atexit` hook, so the host owns every flush:
+
+```python
+from mcp.server.mcpserver import MCPServer
+from mcpsignals import handle_for, instrument
+
+
+async def handle_request(request):
+    server = MCPServer("my-server")
+    instrument(
+        server,
+        server_name="my-server",
+        sinks=[...],
+        flush_interval_s=None,  # manual mode: the host flushes explicitly
+    )
+
+    @server.tool()
+    def search(query: str) -> str:
+        return f"results for {query}"
+
+    response = await serve(request, server)
+
+    await handle_for(server).flush()  # before returning the response
+    return response
+```
+
+Call `close()` instead of `flush()` when the server is done for good: at the
+end of a test, or when a per-request server is discarded. In the default
+interval mode, `close()` is also what stops the interval task and removes the
+`atexit` hook, so a test suite that instruments many servers does not
+accumulate either. Both `flush()` and `close()` are safe to await more than
+once.
+
 ## Known limitation: `session_id`
 
 `mcp` 2.0.0's middleware-facing `ServerRequestContext` does not publicly

{mcpsignals-2.0.2 → mcpsignals-2.2.0}/pyproject.toml

@@ -8,7 +8,7 @@ name = "mcpsignals"
 # stamps the real version in at release time and never commits it back, exactly
 # as packages/node/package.json is left at 0.1.0. Do not read this as the
 # published version - check PyPI or the git tags for that.
-version = "2.0.2"
+version = "2.2.0"
 description = "Drop-in instrumentation for MCP servers. Writes tool-call events to a database you own."
 readme = "README.md"
 license = "MIT"

{mcpsignals-2.0.2 → mcpsignals-2.2.0}/src/mcpsignals/__init__.py

@@ -1,9 +1,12 @@
 from mcpsignals.events import SessionSummaryEvent, ToolCallEvent
+from mcpsignals.handle import InstrumentHandle, handle_for
 from mcpsignals.instrument import instrument
 from mcpsignals.redaction import RedactionConfig
 
 __all__ = [
     "instrument",
+    "handle_for",
+    "InstrumentHandle",
     "RedactionConfig",
     "ToolCallEvent",
     "SessionSummaryEvent",

mcpsignals-2.2.0/src/mcpsignals/buffer.py

@@ -0,0 +1,149 @@
+"""Batches events and flushes to every configured sink on a size threshold
+or an interval, whichever comes first. A sink failure is caught, logged at
+most once per sink instance, and never propagates - a broken sink must
+never break the host MCP server.
+
+Pass `flush_interval_s=None` for manual mode: no interval task, no `atexit`
+hook, the caller flushes explicitly (via `handle_for(server).flush()`).
+"""
+
+import asyncio
+import atexit
+import logging
+from collections.abc import Sequence
+
+from mcpsignals.events import SessionSummaryEvent, ToolCallEvent
+from mcpsignals.sinks.base import Sink
+
+logger = logging.getLogger("mcpsignals")
+
+Event = ToolCallEvent | SessionSummaryEvent
+
+
+class EventBuffer:
+    def __init__(
+        self,
+        sinks: Sequence[Sink],
+        buffer_size: int = 20,
+        flush_interval_s: float | None = 5.0,
+    ):
+        self._sinks = list(sinks)
+        self._buffer_size = buffer_size
+        self._flush_interval_s = flush_interval_s
+        self._events: list[Event] = []
+        self._lock = asyncio.Lock()
+        self._warned_sinks: set[int] = set()
+        self._interval_task: asyncio.Task | None = None
+        # The interval task's current flush, if one is in progress. Kept
+        # outside the task (and shielded from its cancellation) so close()
+        # can wait for a write that already left the buffer.
+        self._inflight: asyncio.Future | None = None
+        # Manual mode (`flush_interval_s=None`) never starts the interval task
+        # and never registers the atexit hook. `stop()` flips this too, so a
+        # later `add()` cannot silently restart the task.
+        self._stopped = flush_interval_s is None
+        if flush_interval_s is not None:
+            atexit.register(self._atexit_flush)
+
+    def _ensure_interval_task(self) -> None:
+        # Started lazily on first event, from inside a running event loop -
+        # constructing EventBuffer itself must not require a loop to exist yet.
+        if self._stopped or self._interval_task is not None:
+            return
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return
+        self._interval_task = loop.create_task(self._interval_loop())
+
+    async def _interval_loop(self) -> None:
+        while True:
+            await asyncio.sleep(self._flush_interval_s)  # type: ignore[arg-type]
+            # Shielded: cancelling this task (stop()/close()) must not abort a
+            # sink write whose batch has already been popped from the buffer.
+            # CancelledError is a BaseException, so _write_to_sink's `except
+            # Exception` would not catch it and the batch would be lost.
+            self._inflight = asyncio.ensure_future(self.flush())
+            await asyncio.shield(self._inflight)
+
+    async def add(self, event: Event) -> None:
+        self._ensure_interval_task()
+        async with self._lock:
+            self._events.append(event)
+            should_flush = len(self._events) >= self._buffer_size
+        if should_flush:
+            await self.flush()
+
+    async def flush(self) -> None:
+        async with self._lock:
+            if not self._events:
+                return
+            batch, self._events = self._events, []
+
+        # Each _write_to_sink swallows and logs its own failure, so nothing
+        # here needs to inspect the results.
+        await asyncio.gather(
+            *(self._write_to_sink(sink, batch) for sink in self._sinks),
+            return_exceptions=True,
+        )
+
+    def stop(self) -> None:
+        """Cancel the interval task (if one is running) and unregister the
+        atexit hook. Safe to call in manual mode, and safe to call twice.
+        Does not flush, and leaves an in-flight interval write untouched:
+        use `close()` for a final flush plus stop.
+        """
+        self._stopped = True
+        if self._interval_task is not None:
+            self._interval_task.cancel()
+            self._interval_task = None
+        # No-op when the hook was never registered (manual mode, or an
+        # earlier stop() already removed it).
+        atexit.unregister(self._atexit_flush)
+
+    async def close(self) -> None:
+        """`stop()`, wait for the interval task and any write it already had
+        in flight to settle, then a final `flush()`. Nothing is left running
+        on the loop and no popped batch is dropped. Idempotent.
+        """
+        task = self._interval_task
+        self.stop()
+        if task is not None:
+            # Not `suppress(CancelledError)` around `await task`: a
+            # cancellation aimed at close() itself surfaces at that same await
+            # and would be swallowed too. gather(return_exceptions=True) hands
+            # the interval task's own CancelledError back as a value while a
+            # cancel of close() still raises out of the await. (3.10-safe:
+            # `Task.cancelling()` is 3.11+.)
+            await asyncio.gather(task, return_exceptions=True)
+        inflight = self._inflight
+        if inflight is not None and not inflight.done():
+            # Shielded again so cancelling close() itself lets the write finish.
+            await asyncio.shield(inflight)
+        await self.flush()
+
+    async def _write_to_sink(self, sink: Sink, batch: list[Event]) -> None:
+        try:
+            await sink.write(batch)
+        except Exception as exc:  # noqa: BLE001 - a sink must never break the host server
+            sink_id = id(sink)
+            if sink_id not in self._warned_sinks:
+                self._warned_sinks.add(sink_id)
+                logger.error("mcpsignals: sink %r failed, dropping batch: %s", sink, exc)
+
+    def _atexit_flush(self) -> None:
+        if not self._events:
+            return
+        # Best-effort only: there is no guarantee a loop is available to
+        # await a real flush at interpreter shutdown. Callers that need a
+        # guaranteed flush should `await handle_for(server).flush()` (or
+        # `.close()`) explicitly before shutting down.
+        try:
+            asyncio.run(self.flush())
+        except RuntimeError:
+            logger.warning(
+                "mcpsignals: %d buffered event(s) dropped at exit (no event loop available "
+                "to flush) - call `await handle_for(server).flush()` explicitly before "
+                "shutdown for a guarantee",
+                len(self._events),
+            )

mcpsignals-2.2.0/src/mcpsignals/handle.py

@@ -0,0 +1,58 @@
+"""The host's way to reach the buffer behind an instrumented server.
+
+`instrument()` keeps returning the server object unchanged (so existing
+callers are not affected); the handle is looked up separately through
+`handle_for(server)`. The registry is a `weakref.WeakKeyDictionary` keyed
+by the exact server object passed to `instrument()`: the handle lives
+exactly as long as that server object does and is dropped with it, so a
+per-request server does not leak its buffer.
+"""
+
+import weakref
+from typing import Any
+
+from mcpsignals.buffer import EventBuffer
+
+
+class InstrumentHandle:
+    """Returned by `handle_for(server)` for a server that went through
+    `instrument()`. `flush()` delivers everything buffered so far to every
+    sink; `close()` does a final flush, cancels the interval task, and
+    unregisters the atexit hook. Both are safe to await more than once.
+    """
+
+    def __init__(self, buffer: EventBuffer):
+        self._buffer = buffer
+
+    async def flush(self) -> None:
+        """Flush buffered events to every sink now. On a request-scoped
+        runtime, or in manual mode (`flush_interval_s=None`), call this
+        before returning the response.
+        """
+        await self._buffer.flush()
+
+    async def close(self) -> None:
+        """Final flush, then stop: cancel the interval task if one is
+        running and unregister the atexit hook. Call this when the server
+        is done for good - at the end of a test, or when a per-request
+        server is discarded. Idempotent.
+        """
+        await self._buffer.close()
+
+
+_registry: weakref.WeakKeyDictionary[Any, InstrumentHandle] = weakref.WeakKeyDictionary()
+
+
+def register(server: Any, handle: InstrumentHandle) -> None:
+    _registry[server] = handle
+
+
+def handle_for(server: Any) -> InstrumentHandle | None:
+    """The `InstrumentHandle` for `server`, or `None` if that exact object
+    never went through `instrument()`.
+    """
+    try:
+        return _registry.get(server)
+    except TypeError:
+        # Not hashable or not weakly referenceable: cannot have been registered.
+        return None

{mcpsignals-2.0.2 → mcpsignals-2.2.0}/src/mcpsignals/instrument.py

@@ -5,15 +5,17 @@ present on both `MCPServer` and the low-level `Server` - the same mechanism
 works for both, no separate code paths needed. See
 https://py.sdk.modelcontextprotocol.io/v2/advanced/middleware/.
 
-Known SDK limitation (verified against the installed mcp==2.0.0 source,
-mcp/server/context.py): `ServerRequestContext` - what middleware receives -
-does not publicly expose the transport's connection-level session id or a
-`connection` accessor (only the handler-facing `Context` class does, via a
-private `Connection` it doesn't share with middleware). We do not reach into
-that private attribute. As a result `session_id` on emitted events is only
-ever populated from the optional intent-capture value the calling agent
-supplies - it is `None` for calls where intent capture is off or the caller
-didn't pass one, even though the connection may well have a real session id.
+Known SDK limitation (first verified against mcp==2.0.0, re-checked against
+the mcp==2.2.0 that a fresh `uv sync` resolves; mcp/server/context.py):
+`ServerRequestContext` - what middleware receives - does not publicly expose
+the transport's connection-level session id or a `connection` accessor
+(only the handler-facing `Context` class does, via a private `Connection`
+it doesn't share with middleware; `ctx.session` is a `ServerSession`, which
+has no session id either). We do not reach into that private attribute. As
+a result `session_id` on emitted events is only ever populated from the
+optional intent-capture value the calling agent supplies - it is `None` for
+calls where intent capture is off or the caller didn't pass one, even though
+the connection may well have a real session id.
 Track https://github.com/modelcontextprotocol/python-sdk for this being
 exposed to middleware in a future release.
 """
@@ -29,6 +31,8 @@ from typing import Any
 from mcpsignals.buffer import EventBuffer
 from mcpsignals.error_kind import classify_error
 from mcpsignals.events import ToolCallEvent
+from mcpsignals.handle import InstrumentHandle
+from mcpsignals.handle import register as _register_handle
 from mcpsignals.intent_capture import enabled_for, inject_schema, strip_injected
 from mcpsignals.redaction import RedactionConfig, redact_arguments
 from mcpsignals.sinks.base import Sink
@@ -86,15 +90,21 @@ def instrument(
     intent_capture_tools: Mapping[str, bool] | None = None,
     resolve_identity: ResolveIdentity | None = None,
     buffer_size: int = 20,
-    flush_interval_s: float = 5.0,
+    flush_interval_s: float | None = 5.0,
 ) -> Any:
     """Wrap `server` (an `MCPServer` or a low-level `Server`) so every tool
     call is recorded as a `tool_call` event, per schema/events.md. Appends
     one middleware function; call this once, right after constructing your
     server. Returns the same instance, unmodified otherwise.
+
+    `handle_for(server)` then returns an `InstrumentHandle` with `flush()`
+    and `close()`. Pass `flush_interval_s=None` for manual mode: no interval
+    task and no atexit hook, so the host flushes explicitly through the
+    handle (request-scoped runtimes, tests, per-request servers).
     """
     active_sinks: list[Sink] = list(sinks) if sinks else [ConsoleSink()]
     buffer = EventBuffer(active_sinks, buffer_size=buffer_size, flush_interval_s=flush_interval_s)
+    _register_handle(server, InstrumentHandle(buffer))
 
     async def _mcpsignals_middleware(ctx, call_next):
         if ctx.method == "tools/list":

{mcpsignals-2.0.2 → mcpsignals-2.2.0}/src/mcpsignals/sinks/bigquery.py

@@ -3,10 +3,16 @@ Credentials come from Application Default Credentials, same as the client
 library's own defaults - never an invented config file. The client library
 is synchronous, so writes run in a thread via asyncio.to_thread and never
 block the event loop.
+
+Rows go through `insert_rows_json` (`tabledata.insertAll`), which applies no
+type conversion. A `JSON` column expects a JSON string on that path, so
+`arguments` is encoded with `json.dumps` before insert - the same thing the
+client library's own `insert_rows` does for JSON fields (`_helpers._json_to_json`).
 """
 
 import asyncio
 import dataclasses
+import json
 
 from mcpsignals.events import SessionSummaryEvent, ToolCallEvent
 
@@ -28,6 +34,10 @@ class BigQuerySink:
         row = dataclasses.asdict(event)
         row.pop("event_type", None)
         row["ts"] = event.ts.isoformat() if event.ts else None
+        if isinstance(event, ToolCallEvent):
+            row["arguments"] = (
+                json.dumps(row["arguments"]) if row["arguments"] is not None else None
+            )
         return row
 
     def _insert_sync(self, table: str, rows: list[dict]) -> None:

mcpsignals-2.2.0/src/mcpsignals/sinks/console.py

@@ -0,0 +1,28 @@
+import dataclasses
+import json
+import sys
+from typing import TextIO
+
+from mcpsignals.events import SessionSummaryEvent, ToolCallEvent
+
+
+class ConsoleSink:
+    """The default sink. Zero configuration, writes one JSON line per event
+    to stdout so the library is useful without setting up a warehouse.
+
+    `stream` picks where the lines go. `None` (the default) resolves to
+    `sys.stdout` at write time, so output redirection and test capture that
+    replace `sys.stdout` still apply. On a stdio transport, stdout is the MCP
+    wire: the spec says the server MUST NOT write anything to stdout that is
+    not a valid MCP message, and MAY log to stderr. Pass `sys.stderr` there.
+    """
+
+    def __init__(self, stream: TextIO | None = None) -> None:
+        self._stream = stream
+
+    async def write(self, events: list[ToolCallEvent | SessionSummaryEvent]) -> None:
+        stream = self._stream if self._stream is not None else sys.stdout
+        for event in events:
+            payload = dataclasses.asdict(event)
+            payload["ts"] = event.ts.isoformat() if event.ts else None
+            print(json.dumps(payload, default=str), file=stream, flush=True)

{mcpsignals-2.0.2 → mcpsignals-2.2.0}/src/mcpsignals/sinks/otlp.py

@@ -1,6 +1,8 @@
 """OTLP sink. Requires the `otlp` extra (opentelemetry-api only, not an SDK
 or exporter - relies on whatever global TracerProvider the host app already
-configured, the standard "zero-code" OTel pattern).
+configured, the standard "zero-code" OTel pattern). Emits one root span per
+tool call; spans are never parented to the context current at flush time
+(see the note at `start_span` in `write`).
 
 Field mapping verified against the live OpenTelemetry GenAI semantic
 conventions for MCP (open-telemetry/semantic-conventions-genai,
@@ -24,6 +26,7 @@ class OtlpSink:
         self._tracer = tracer
 
     async def write(self, events: list[ToolCallEvent | SessionSummaryEvent]) -> None:
+        from opentelemetry.context import Context
         from opentelemetry.trace import SpanKind, Status, StatusCode
 
         for event in events:
@@ -71,8 +74,13 @@ class OtlpSink:
             start_ns = int(event.ts.timestamp() * 1_000_000_000) if event.ts else None
             end_ns = start_ns + event.duration_ms * 1_000_000 if start_ns is not None else None
 
+            # The batch is usually written from inside whatever request handler
+            # pushed the last event, so the current context (the default
+            # parent) belongs to an unrelated span. Start from an empty
+            # Context so every tool call is its own root span.
             span = self._tracer.start_span(
                 f"tools/call {event.tool_name}",
+                context=Context(),
                 kind=SpanKind.SERVER,
                 attributes=attributes,
                 start_time=start_ns,

mcpsignals-2.2.0/tests/test_bigquery.py

@@ -0,0 +1,119 @@
+import json
+from datetime import datetime, timezone
+
+import pytest
+from mcpsignals.events import SessionSummaryEvent, ToolCallEvent
+from mcpsignals.sinks.bigquery import BigQuerySink
+
+TS = datetime(2026, 9, 1, 23, 25, 24, tzinfo=timezone.utc)
+
+
+class FakeClient:
+    """Records insert_rows_json(table_ref, rows) calls. Returns `errors` (an
+    empty list means success, matching google-cloud-bigquery's contract)."""
+
+    def __init__(self, errors=None):
+        self.calls: list[tuple[str, list[dict]]] = []
+        self.errors = errors if errors is not None else []
+
+    def insert_rows_json(self, table_ref, rows):
+        self.calls.append((table_ref, rows))
+        return self.errors
+
+
+def make_tool_call(**overrides) -> ToolCallEvent:
+    defaults = dict(ts=TS, server_name="s", tool_name="my-tool", duration_ms=5)
+    defaults.update(overrides)
+    return ToolCallEvent(**defaults)
+
+
+def make_session_summary(**overrides) -> SessionSummaryEvent:
+    defaults = dict(ts=TS, session_id="sess-1", server_name="s", call_count=1)
+    defaults.update(overrides)
+    return SessionSummaryEvent(**defaults)
+
+
+async def test_tool_call_rows_go_to_the_tool_call_table():
+    client = FakeClient()
+    sink = BigQuerySink(dataset="d", client=client)
+
+    await sink.write([make_tool_call()])
+
+    assert [table_ref for table_ref, _ in client.calls] == ["d.tool_call"]
+    assert len(client.calls[0][1]) == 1
+
+
+async def test_session_summary_rows_go_to_the_session_summary_table():
+    client = FakeClient()
+    sink = BigQuerySink(dataset="d", client=client)
+
+    await sink.write([make_session_summary()])
+
+    assert [table_ref for table_ref, _ in client.calls] == ["d.session_summary"]
+    row = client.calls[0][1][0]
+    assert row["session_id"] == "sess-1"
+    assert "event_type" not in row
+
+
+async def test_arguments_are_sent_as_a_json_string_for_the_json_column():
+    # tabledata.insertAll expects a JSON-typed column as a JSON string, which
+    # is what google-cloud-bigquery's own insert_rows() does for JSON fields
+    # (_helpers._json_to_json). insert_rows_json applies no conversion, so the
+    # sink has to encode the dict itself.
+    client = FakeClient()
+    sink = BigQuerySink(dataset="d", client=client)
+    event = make_tool_call(arguments={"a": 1, "nested": {"b": [1, 2]}})
+
+    await sink.write([event])
+
+    row = client.calls[0][1][0]
+    assert isinstance(row["arguments"], str)
+    assert row["arguments"] == json.dumps(event.arguments)
+
+
+async def test_null_arguments_stay_null():
+    client = FakeClient()
+    sink = BigQuerySink(dataset="d", client=client)
+
+    await sink.write([make_tool_call(arguments=None)])
+
+    assert client.calls[0][1][0]["arguments"] is None
+
+
+async def test_ts_is_iso_formatted_and_event_type_is_dropped():
+    client = FakeClient()
+    sink = BigQuerySink(dataset="d", client=client)
+
+    await sink.write([make_tool_call()])
+
+    row = client.calls[0][1][0]
+    assert row["ts"] == "2026-09-01T23:25:24+00:00"
+    assert "event_type" not in row
+
+
+async def test_mixed_batch_makes_one_insert_per_event_type():
+    client = FakeClient()
+    sink = BigQuerySink(dataset="d", client=client)
+
+    await sink.write([make_tool_call(), make_session_summary(), make_tool_call(tool_name="other")])
+
+    assert [table_ref for table_ref, _ in client.calls] == ["d.tool_call", "d.session_summary"]
+    assert len(client.calls[0][1]) == 2
+    assert len(client.calls[1][1]) == 1
+
+
+async def test_empty_batch_never_calls_the_client():
+    client = FakeClient()
+    sink = BigQuerySink(dataset="d", client=client)
+
+    await sink.write([])
+
+    assert client.calls == []
+
+
+async def test_insert_errors_raise():
+    client = FakeClient(errors=[{"index": 0, "errors": [{"reason": "invalid"}]}])
+    sink = BigQuerySink(dataset="d", client=client)
+
+    with pytest.raises(RuntimeError, match="d.tool_call"):
+        await sink.write([make_tool_call()])