bug: timeline span `seq` names a different event per span kind, and all five are undocumented
Maintainer thường phản hồi trong vòng 1 ngày
Chưa có ai nhận issue này.
Đánh giá
- Độ khó
- 4/5
- Thời gian dự kiến
- 3-5 ngày
- Mức phù hợp với người mới
- 35/100
Hướng nghiên cứu
Start in core/session/timeline/timeline.go, where the five span structs declare a bare Seq field, then check agents.go (around lines 125-202) and hosts.go (lines 54 and 63) to confirm which event each one sets. The issue leaves open whether to rename the field with a deprecation period or only add doc comments, so settle that with a maintainer first. Done means each span's seq meaning is stated in code and in docs/session-api.md.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Mô tả
Summary
GET /v1/sessions/{id}/timeline returns five span kinds, each with a seq. Four name the request event; one names the response. All five fields are undocumented, in a package where every other field carries a paragraph.
A consumer joining timeline spans to event data on seq therefore matches nothing for four of the five kinds — and gets no error, just an empty result, which is the failure mode that costs the most time to diagnose.
The actual mapping
On main (core/session/timeline/):
| Span | Declared | Set at | seq is the |
|---|---|---|---|
Turn |
timeline.go:88 |
agents.go:176 — Seq: c.req.Seq |
request event |
Tool |
timeline.go:105 |
agents.go:202 — Seq: c.resp.Seq |
response event |
Job |
timeline.go:118 |
agents.go:125 — Seq: c.req.Seq |
request event |
Return |
timeline.go:126 |
agents.go:161 — Seq: c.req.Seq |
request event |
Host |
timeline.go:138 |
hosts.go:54, :63 — Seq: e.Seq |
the event it came from |
Every one of those five declarations is a bare Seq uint64 \json:"seq"`with no comment. Compare the fields around them —Resent, Error, Model, ToolUseID` all have one, several of them a full paragraph.
How it bites
Token counts live on the response event (inference.inputTokens and friends). So the natural query — "show me each model call's latency beside its tokens" — joins turns[].seq to a response event and silently returns nothing:
# Returns a header and zero rows. No error.
jq -n --slurpfile tl tl.json --slurpfile ev ev.json '
($ev[0].events | map(select(.phase=="response")) | INDEX(.seq|tostring)) as $byseq
| $tl[0].turns[] | select($byseq[(.seq|tostring)] != null)'
Measured on a 2,911-event session: 0 of 509 turns[].seq values in the paged range matched a response event. Switching to tools[].seq matched 458 of 592 immediately.
It cost two people on #1854 — once writing the query, once a reviewer who went to core/sessionapi/timeline.go (a real, different file) chasing the bare timeline.go:88 citation and found cache internals.
Proposed fix
Rename, do not just document. The names are the trap: identical field name, identical type, different referent, and nothing at the call site to warn you.
type Turn struct {
// RequestSeq is the seq of the REQUEST event this turn began at. Token counts and
// the status live on the matching RESPONSE event — pair by requestId, not by this.
RequestSeq uint64 `json:"requestSeq"`
}
type Tool struct {
// ResponseSeq is the seq of the RESPONSE event that asked for this tool, so it joins
// directly to that event's inference fields.
ResponseSeq uint64 `json:"responseSeq"`
}
That is a wire change, so it needs the usual skew handling: emit both keys for a release (seq plus the new name), with seq documented as deprecated, then drop it. agentop is the only in-tree consumer.
If a rename is too invasive, the minimum is a doc comment on each of the five saying which event it names, plus the mapping table above in docs/session-api.md. That is already done on the docs side in #1854, but the struct fields themselves remain bare — and a consumer reads the struct, not someone else's spec.
Also worth fixing alongside
/timeline reads up to 50,000 events; GET /v1/sessions/{id} caps ?limit at 2,000. Both numbers are documented, 70 lines apart in session-api.md, and never related to each other. On the same 2,911-event session a single-page join covers only the newest 2,000 events, so 134 of 592 tool spans have no matching event row unless the consumer pages with ?before=. #1854 documents this; the asymmetry itself may still be worth closing.
Scope note
Found while writing the queries in #1854's §9.3, against one developer's laptop archive (66 sessions, 29,606 events). The mapping generalises — it follows the code, not this traffic. The match counts above are from one 2,911-event session.
Refs #1854, #1810
- Ngôn ngữ chính
- Go
- Star
- 26
- Fork
- 46
- Merge trung bình
- 9 giờ 55 phút
- Pull request đã merge (30 ngày)
- 257
Chuẩn bị môi trường
- Không có Dockerfile hay tệp Docker Compose
- Không có mẫu pull request
- Đọc hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của rossoctl/cortex
-
bug laptop
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 75/100
Maintainer thường phản hồi trong vòng 1 ngày
-
bug laptop
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
Maintainer thường phản hồi trong vòng 1 ngày
-
feat: Do not count a removed session's cost again when an import brings it backCó thể đã có người làm @huang195 đã nhận hôm nay. Đang mởenhancement
rossoctl/cortex#1885 · 1 người được giao ·
Maintainer thường phản hồi trong vòng 1 ngày
-
bug: The JWT bypass matches a cleaned path but forwards the raw path, so /mcp/../healthz skips validationCó thể đã có người làm @evaline-ju đã nhận hôm nay. Đang mởbug
rossoctl/cortex#1884 · 1 người được giao ·
Maintainer thường phản hồi trong vòng 1 ngày
-
bug: One-hour Anthropic cache writes are priced at the 5-minute rate, so spend is 37.5% too lowĐang mởbug
Độ khó 3/5 1-2 ngày Mức phù hợp với người mới 78/100
Maintainer thường phản hồi trong vòng 1 ngày
Tất cả issue của rossoctl/cortex
Issue tương tự
-
Type: Bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 82/100
projectdiscovery/httpx#2735 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 76/100
charmbracelet/huh#849 ·
-
help wanted stage/010-actionable
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 65/100
hivecommons/hive#18458 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
enhancement
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
suzuki-shunsuke/tfcmt#2636 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
ui: links opened in a new tab omit the public URL path prefix (e.g. rotations on a schedule's assignments page)Có thể đã có người làm @dginther đã nhận hôm nay. Đang mởbug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 85/100
Maintainer thường phản hồi trong vòng 1 ngày