Skip to content

Commit b88b852

Browse files
nik13claude
andcommitted
feat(hook-to-otlp): keyless turns, FIFO tool pairing, one open turn per session
Additive core changes requested by the Kiro/Antigravity/Devin Desktop children; existing adapters (Cursor) are unaffected. - A TURN START with an empty key opens turn-1, turn-2, ... per session; a keyless TURN END/UPDATE applies to the open turn (ignored if none). - A keyless END of a tool/subagent/llm/event span pairs with the oldest open keyless START of the same scope and name (FIFO), for pre/post hooks without call ids. - A TURN START closes any other open turn of the session (and its children) as incomplete; a late END for that turn re-sends it complete with its original start. - respond(): an adapter returning "" prints nothing (Kiro and Claude Code add hook stdout to the model context); None still means "{}". Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 6ba7e39 commit b88b852

4 files changed

Lines changed: 143 additions & 3 deletions

File tree

‎examples/coding-agents/hook-to-otlp/README.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,9 @@ process so the host is not kept waiting.
6060
from the payload, else the hook time. A turn opens on the first event that names it.
6161
- A turn end closes still-open children of that turn (`coding_agent.incomplete=true`);
6262
a session end closes everything and deletes the state file.
63+
- One turn is open per session: a turn START closes any other open turn (and its
64+
children) as incomplete. If that turn's END arrives later, the turn is re-sent complete
65+
with its original start.
6366
- Every span carries `session.id`, `gen_ai.conversation.id`, `coding_agent.app`,
6467
`coding_agent.scope`, `coding_agent.hook.event`, and `coding_agent.turn.id` when known.
6568
Tool spans add `gen_ai.tool.name` and `gen_ai.tool.call.id`; session/turn/llm/subagent
@@ -87,7 +90,7 @@ def parse(event: str, payload: dict) -> list: # required
8790
return []
8891

8992
def respond(event: str, payload: dict) -> str: # optional, default "{}"
90-
return "{}"
93+
return "{}" # "" prints nothing (hosts that add stdout to the model context)
9194

9295
def event_name(argv_event, payload): # optional
9396
return argv_event or payload.get("hook_event_name")
@@ -104,6 +107,10 @@ input=None, output=None, error_message=None)`:
104107
`UPDATE` merges into an open span (for example a response text into the turn).
105108
- `scope`: `SESSION`, `TURN`, `TOOL`, `SUBAGENT`, `LLM`, `EVENT`.
106109
- `key` pairs START/END of the same scope (tool call id, turn id). Empty for the session.
110+
Apps without ids can leave it empty: a keyless TURN START opens `turn-1`, `turn-2`, ...
111+
and a keyless TURN END/UPDATE applies to the open turn (ignored if none); a keyless
112+
END of another scope pairs with the oldest open keyless START of the same scope and
113+
`name` (FIFO), else it becomes a standalone span.
107114
- `turn_id` parents a tool/subagent/llm/event span; None means the open turn, else the session.
108115
- `status` is `OK`, `ERROR` or None. `status_message` is always exported, so keep it to
109116
metadata (`"timeout"`), never free text.

‎examples/coding-agents/hook-to-otlp/emit.py‎

Lines changed: 54 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
from __future__ import annotations
2121

2222
import contextlib
23+
import dataclasses
2324
import hashlib
2425
import importlib
2526
import json
@@ -65,6 +66,7 @@
6566
re.compile(r"(?i)\b((?:api[_-]?key|secret[_-]?key|access[_-]?token|password|passwd|token)\b[\"']?\s*[:=]\s*[\"']?)[^\s\"',}]+"),
6667
)
6768
MAX_ENDED_TURNS = 64
69+
MAX_ENDED_RECS = 8
6870

6971

7072
@dataclass
@@ -405,12 +407,42 @@ def _end_turn(self, key: str, rec: Dict[str, Any], event: str) -> None:
405407
ended = self.state["ended_turns"]
406408
ended.append(key)
407409
del ended[:-MAX_ENDED_TURNS]
410+
recs = self.state.setdefault("ended_recs", {})
411+
recs.pop(key, None)
412+
recs[key] = dict(rec)
413+
while len(recs) > MAX_ENDED_RECS:
414+
recs.pop(next(iter(recs)))
408415
if self.state.get("current_turn") == key:
409416
self.state["current_turn"] = None
410417

418+
def _resolve_turn_key(self, ev: SpanEvent) -> Optional[str]:
419+
"""Key for a TURN event that has none (apps without turn ids).
420+
421+
START mints the next per-session key (turn-1, turn-2, ...); END and
422+
UPDATE apply to the currently open turn, if any.
423+
"""
424+
if ev.phase == START:
425+
seq = int(self.state.get("turn_seq", 0)) + 1
426+
self.state["turn_seq"] = seq
427+
return f"turn-{seq}"
428+
return self.state.get("current_turn")
429+
430+
def _oldest_open(self, scope: str, name: Optional[str]) -> Optional[str]:
431+
"""Key of the oldest open keyless START of ``scope`` with this name (FIFO pairing)."""
432+
candidates = [rec for rec in self.state["open"].values()
433+
if rec["scope"] == scope and rec.get("synthetic_key") and rec.get("name") == name]
434+
if not candidates:
435+
return None
436+
return min(candidates, key=lambda rec: rec["start_ns"])["key"]
437+
411438
# -- main entry
412439

413440
def apply(self, ev: SpanEvent, event: str) -> None:
441+
if ev.scope == TURN and not ev.key:
442+
resolved = self._resolve_turn_key(ev)
443+
if not resolved:
444+
return
445+
ev = dataclasses.replace(ev, key=resolved)
414446
start_ns = self._start_of(ev)
415447
session = self._ensure_session(start_ns)
416448
if ev.model:
@@ -430,6 +462,8 @@ def apply(self, ev: SpanEvent, event: str) -> None:
430462

431463
key = ev.key
432464
synthetic = False
465+
if not key and ev.phase == END:
466+
key = self._oldest_open(ev.scope, ev.name) or ""
433467
if not key:
434468
key, synthetic = secrets.token_hex(8), True
435469
slot = f"{ev.scope}:{key}"
@@ -468,6 +502,13 @@ def _apply_turn(self, ev: SpanEvent, event: str, start_ns: int) -> None:
468502
return
469503
slot = f"{TURN}:{key}"
470504
if ev.phase == START:
505+
# One turn at a time per session: a new turn closes any other open
506+
# turn as incomplete (apps that sometimes skip their turn-end hook).
507+
for other_slot, other in list(self.state["open"].items()):
508+
if other["scope"] == TURN and other["key"] != key:
509+
del self.state["open"][other_slot]
510+
other["incomplete"] = True
511+
self._end_turn(other["key"], other, event)
471512
if key in self.state["ended_turns"]:
472513
self.state["ended_turns"].remove(key)
473514
rec = self._ensure_turn(key, start_ns)
@@ -481,7 +522,15 @@ def _apply_turn(self, ev: SpanEvent, event: str, start_ns: int) -> None:
481522
else:
482523
rec = self.state["open"].pop(slot, None)
483524
if rec is None:
484-
rec = {"scope": TURN, "key": key, "start_ns": start_ns, "attrs": {}, "parent": self.root}
525+
late = self.state.get("ended_recs", {}).pop(key, None)
526+
if late is not None:
527+
# The turn was closed as incomplete; re-send it complete with its original start.
528+
rec = late
529+
rec.pop("incomplete", None)
530+
if key in self.state["ended_turns"]:
531+
self.state["ended_turns"].remove(key)
532+
else:
533+
rec = {"scope": TURN, "key": key, "start_ns": start_ns, "attrs": {}, "parent": self.root}
485534
self._merge(rec, ev)
486535
self._end_turn(key, rec, event)
487536

@@ -544,9 +593,12 @@ def respond(adapter: Any, event: str, payload: Dict[str, Any]) -> str:
544593
if fn is None:
545594
return "{}"
546595
try:
547-
return fn(event, payload) or "{}"
596+
out = fn(event, payload)
548597
except Exception:
549598
return "{}"
599+
# None means "use the default"; "" means "print nothing" (hosts that add
600+
# hook stdout to the model context).
601+
return "{}" if out is None else str(out)
550602

551603

552604
def build_spans(adapter: Any, cfg: Config, event: str, payload: Dict[str, Any],

‎examples/coding-agents/hook-to-otlp/tests/test_core.py‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33

44
import json
55
import os
6+
import sys
67
import tempfile
78
import time
89
import types
@@ -105,6 +106,84 @@ def test_session_without_activity_exports_nothing(self):
105106
self.assertEqual(self.run_hooks(adapter, [(0, "s"), (10, "e")]), [])
106107
self.assertEqual(list(self.cfg.state_dir.glob("*.json")), [])
107108

109+
def test_keyless_turns_get_per_session_keys(self):
110+
# Apps without turn ids (Kiro, Antigravity): START mints turn-N, END/UPDATE use the open turn.
111+
adapter = scripted({
112+
"prompt": [SpanEvent(START, TURN, "S", input="P")],
113+
"tool": [SpanEvent(END, TOOL, "S", name="Shell", duration_ms=100)],
114+
"reply": [SpanEvent(UPDATE, TURN, "S", output="R")],
115+
"stop": [SpanEvent(END, TURN, "S", status=OK)],
116+
})
117+
spans = self.run_hooks(adapter, [(0, "prompt"), (500, "tool"), (600, "reply"), (700, "stop"),
118+
(800, "prompt"), (900, "stop"), (950, "stop")])
119+
turn1 = emit.span_id("fake", "S", TURN, "turn-1")
120+
turn2 = emit.span_id("fake", "S", TURN, "turn-2")
121+
tool = [s for s in spans if s["name"] == "Shell"][0]
122+
self.assertEqual(tool["parentSpanId"], turn1)
123+
t1 = latest(spans, turn1)
124+
self.assertEqual(int(t1["endTimeUnixNano"]) - int(t1["startTimeUnixNano"]), 700 * MS)
125+
self.assertEqual(attrs(t1)["coding_agent.turn.id"], "turn-1")
126+
t2 = latest(spans, turn2)
127+
self.assertEqual(int(t2["endTimeUnixNano"]) - int(t2["startTimeUnixNano"]), 100 * MS)
128+
# The extra stop has no open turn and is ignored.
129+
self.assertEqual(len([s for s in spans if s["spanId"] in (turn1, turn2)]), 2)
130+
131+
def test_keyless_tool_end_pairs_with_oldest_start_of_same_name(self):
132+
# Apps whose pre/post tool hooks carry no call id: FIFO by tool name.
133+
adapter = scripted({
134+
"pre-read": [SpanEvent(START, TOOL, "S", turn_id="g", name="Read")],
135+
"pre-shell": [SpanEvent(START, TOOL, "S", turn_id="g", name="Shell")],
136+
"post-read": [SpanEvent(END, TOOL, "S", turn_id="g", name="Read")],
137+
"post-shell": [SpanEvent(END, TOOL, "S", turn_id="g", name="Shell", status=ERROR)],
138+
})
139+
spans = self.run_hooks(adapter, [(0, "pre-read"), (100, "pre-read"), (200, "pre-shell"),
140+
(300, "post-read"), (400, "post-shell"), (450, "post-read")])
141+
reads = [s for s in spans if s["name"] == "Read"]
142+
self.assertEqual([int(s["endTimeUnixNano"]) - int(s["startTimeUnixNano"]) for s in reads],
143+
[300 * MS, 350 * MS])
144+
shell = [s for s in spans if s["name"] == "Shell"][0]
145+
self.assertEqual(int(shell["endTimeUnixNano"]) - int(shell["startTimeUnixNano"]), 200 * MS)
146+
self.assertEqual(shell["status"]["code"], 2)
147+
self.assertNotIn("gen_ai.tool.call.id", attrs(shell))
148+
149+
def test_turn_start_closes_other_open_turn_and_late_end_corrects_it(self):
150+
adapter = scripted({
151+
"t1": [SpanEvent(START, TURN, "S", key="g1")],
152+
"tool1": [SpanEvent(START, TOOL, "S", key="c1", turn_id="g1", name="Shell")],
153+
"t2": [SpanEvent(START, TURN, "S", key="g2")],
154+
"end1": [SpanEvent(END, TURN, "S", key="g1", status=OK)],
155+
"end2": [SpanEvent(END, TURN, "S", key="g2")],
156+
})
157+
first = self.run_hooks(adapter, [(0, "t1"), (100, "tool1"), (500, "t2")])
158+
g1 = emit.span_id("fake", "S", TURN, "g1")
159+
incomplete = latest(first, g1)
160+
self.assertTrue(attrs(incomplete)["coding_agent.incomplete"])
161+
tool = [s for s in first if s["name"] == "Shell"][0]
162+
self.assertTrue(attrs(tool)["coding_agent.incomplete"], "children of the closed turn are closed too")
163+
# A late end for g1 re-sends it complete, same id and start, without the incomplete flag.
164+
late = self.run_hooks(adapter, [(600, "end1")])
165+
corrected = latest(late, g1)
166+
self.assertEqual(corrected["startTimeUnixNano"], incomplete["startTimeUnixNano"])
167+
self.assertNotIn("coding_agent.incomplete", attrs(corrected))
168+
self.assertEqual(corrected["status"]["code"], 1)
169+
# g2 is still the open turn.
170+
rest = self.run_hooks(adapter, [(900, "end2")])
171+
g2 = latest(rest, emit.span_id("fake", "S", TURN, "g2"))
172+
self.assertEqual(int(g2["endTimeUnixNano"]) - int(g2["startTimeUnixNano"]), 400 * MS)
173+
174+
def test_empty_response_prints_nothing(self):
175+
module = types.ModuleType("adapters.fake_quiet")
176+
module.APP, module.DISPLAY_NAME = "fake_quiet", "Quiet"
177+
module.parse = lambda event, payload: []
178+
module.respond = lambda event, payload: ""
179+
sys.modules["adapters.fake_quiet"] = module
180+
try:
181+
self.assertEqual(emit.run(["fake_quiet", "UserPromptSubmit"], "{}", {}), "")
182+
module.respond = lambda event, payload: None
183+
self.assertEqual(emit.run(["fake_quiet", "UserPromptSubmit"], "{}", {}), "{}")
184+
finally:
185+
del sys.modules["adapters.fake_quiet"]
186+
108187
def test_end_without_start_uses_vendor_duration(self):
109188
adapter = scripted({"post": [SpanEvent(END, TOOL, "S", key="c", name="Read", duration_ms=250)]})
110189
spans = self.run_hooks(adapter, [(1000, "post")])

‎src/pages/docs/integrations/coding-agents/hook-to-otlp.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,8 @@ How the emitter builds the tree:
4141

4242
- The trace id is a hash of the app name and session id, so every hook of a session lands in the same trace without coordination.
4343
- Span ids are derived the same way from the session, the span type, and the app's id for it (turn id, tool call id). A repeated hook overwrites its span instead of duplicating it.
44+
- Apps that do not report turn or tool call ids still get a tree: each prompt hook opens the next turn, and each tool end is paired with the oldest unfinished start of the same tool.
45+
- A new turn closes a previous turn that never reported its end, marking it `coding_agent.incomplete=true` (corrected if the end arrives later).
4446
- Durations come from a matching start hook when the app has one, otherwise from the duration the app reports in the end hook. A small state file per session (in your temp directory, mode 0600) keeps start times between hook processes. It is deleted when the session ends.
4547
- The session span is re-sent with the same id and start time whenever a child span is sent, so it always covers the whole conversation. A conversation that was opened and closed without any activity is not exported.
4648

0 commit comments

Comments
 (0)