Repository navigation
feat(taskq): serve one scrubbed timeline per task to the owner - #19942
Conversation
|
Closing and reopening right after opening so CI runs on hosted runners: same-repo runs from this account queue on the fleet label without a runner (details on #19683). |
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the route only adds a read-only view, gated to the owner, over three stores that already exist. It takes nothing away and changes no route that already exists. Notes
[DESIGN-REVIEWED] 0757b9b Description read[DESCRIPTION-READ] f48ba72df26ea31bdb6783338544cac14212dff383c36b2a2324f4b58af93155 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS The new owner-only GET route has no caller anywhere in the repo, but it is read-only and could be deleted next week without locking anyone out. Notes
What this change shipsInventory (5 items) — 4 justifiedIntent: an owner reads one time-ordered, redacted history of a task instead of joining three records by hand. This is an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 0757b9b Description read[DESCRIPTION-READ] bf515c87395b728e6e067557ea0db594995c5d5bd85b60e113c327bd91861b13 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
|
Thanks for the reviews. One fix commit answers them, and each point is below.
Gates on the new head: the timeline file,
|
|
span=fff1c91d1aa9
|
|
span=12b7dfb4bf33
|
|
span=38f34b109679
|
|
span=2f09ffd7272f
|
|
span=5d7d3a98a4f3
|
|
Closing and reopening so CI runs on hosted runners: same-repo runs from this account queue on the fleet label without a runner (details on #19683). |
e180349 to
74fc9cd
Compare
|
Closing and reopening so CI runs on hosted runners: same-repo runs from this account queue on the fleet label without a runner (details on #19683). |
|
span=38f34b109679
|
74fc9cd to
e35218d
Compare
|
span=fff1c91d1aa9
|
|
span=fff1c91d1aa9 Fixed in fd57d33. The timeline no longer finds a child through the panel's rendered fold. A new read-only resolver, A dispatch past the fold's retain cap has no row in the state either. The stream now reports that as Proof: |
5bed177 to
fd57d33
Compare
|
span=deec9253d54e Fixed in fd57d33, with the first option the review names: each slot unit's fold state is searched, dismissed and omitted rows included. The new read-only A child past the 512-row Proof: |
fd57d33 to
c6b02da
Compare
|
span=b9f3467ba93c Fixed in c6b02da. The timeline no longer resolves the parent's crew-log slot through an open tab. A new Proof: the new tests fail on fd57d33 and pass here. They cover the name list for a Slack key, |
|
|
|
c6b02da to
0757b9b
Compare
|
This needs a maintainer decision before it can merge. The PR adds a new owner-only API route, The review found no blocking defect on head 0757b9b. It checked that the owner gate runs before the task row is read and that all store, crew-log and registry reads run off the event loop. It also checked that every key and leaf is scrubbed before encoding and before the length cut, and that a stream that cannot be read is reported as unavailable or truncated, never as empty. The new test file passed its 137 tests serially, under xdist, in reversed order and in a shuffled order. Security: the route calls Optional:
|
bolichen97
left a comment
There was a problem hiding this comment.
Approving at 0757b9b, without auto since you hold auto-merge.
GET /api/tasks/{task_id}/timelinemerges one task'stask_events, thesubagent/*entries of the session that dispatched it, and, for a workflow agent row, the run's events into one markdown list in time order (taskq/timeline.py). It is a read-only view: nothing is stored or written back, and each stream is read through its owner's existing surface (child_recordandread_pagefor the crew log, the run registry for workflows).- The route is owner-only, and the gate runs before the id is looked up, so a refused caller learns nothing about it.
scrubis a required argument with no default. It runs on every key and leaf before any encoding, on every value before it is cut, and on every rendered line, using the same_scrub_valueas the other task payloads. - Every stream has a bound:
CREW_SCAN_MAX,CREW_ENTRIES_MAX,WORKFLOW_EVENTS_MAXand the detail route's events tail. A stream that cannot be read is reported asunavailableortruncatedwith a reason in the## Streamslist, not dropped, so an empty timeline never reads as "nothing happened". A damaged time (inf,nan, out of range) is counted as unreadable instead of failing the view. crew_log_slots_fortries every slot name a crew-log writer may have used, so a closed tab's log is still found.child_recordreads the fold state, so a child whose card was dismissed still has a history.- No regex in product code, and nothing that newly refuses: it is a new owner-only read.
The newest run of every check on this head is green, and the Opus 5.5 lane reports no findings.
Problem / Motivation
Goal: An owner can read one chronological, redacted account of what happened to a task, without joining three records by hand.
A task's history is recorded in three places that share only the task id:
task_eventsrows of the durable queue, whichGET /api/tasks/{task_id}serves as the last 200 rows;subagent/*entries of the crew log of the session that dispatched it;They use three time spellings (epoch seconds, epoch milliseconds, ISO 8601) and three read paths, so answering "what happened to this task" means opening all three and ordering the lines by hand.
Why it matters
A task that ends
failed,cancelledorunknown_side_effectis diagnosed from its sequence of events: when it was accepted and claimed, what the dispatching session recorded for it, what the workflow run logged around it. Today that sequence exists only as three unrelated records.Not a goal
GET /api/tasks/{task_id}or any other existing task route.What changed (motivation → approach → change)
Approach. A read-only view over the read surfaces that already exist, merged by time. The alternatives were a stored per-task timeline (a fourth copy to keep consistent with three owners) and mirroring queue transitions into the crew log (a second writer of facts the queue owns, and a reconcile question for a transition that lands in one store and not the other). Neither is needed to answer the read.
Route.
GET /api/tasks/{task_id}/timelineinsrc/kiro_crew/dashboard/handlers/tasks.py(api_task_timeline,_timeline_sync), registered inroutes/system.pyand exposed through a lazy wrapper inhandlers/__init__.py(the package must not importtasks.pyat boot). It passes the dashboard's token middleware and thenrequire_owner_dashboard_request(request, "task_timeline")first, so an app token, a non-owner user or a request with no claims is refused (owner_only, or 401 for a stale pre-owner subject) before the row is read. The gate is stricter than the detail route's because the view reaches the spawning session's log and a workflow run. Responses:200 {task_id, markdown, entries}; 404not_foundfor an unknown id; 404unavailablewhen the gateway has no task store; 503unavailablewhen the store read fails. Every read runs inasyncio.to_thread.Renderer. The new
src/kiro_crew/taskq/timeline.py:render_timeline,read_child_entries,events_from_registry, and the typesSources,Timeline,StreamReportandCrewRead, with the named boundsCREW_SCAN_MAX(5000 entries read),CREW_ENTRIES_MAXandWORKFLOW_EVENTS_MAX(200 kept each, newest) andVALUE_MAX_CHARS(300 per rendered value). It is a leaf undertaskq: it importstaskq.modelandtaskq.adapters.runnerand reaches the crew log only throughchild_recordandread_page.task_eventsTaskStore.events, with the detail route's own_EVENTS_TAIL(200) passed increw_logsubagentrowscrew_log_slots_fornames every slot the parent's log may be filed under;child_recordsearches each slot's units for the child in thesubagentsfold state and returns itsseq_spawned; then oneread_pagefrom that seq, filtered tosubagent/*entries withdata.agent_id == task_id. The fold row alone cannot serve it: it keeps one summary per child and does not readsubagent/steeredworkflowworkflow_agentrowseventsread in placeEvery bound is applied before anything is copied or rendered. The queue tail is bounded by the store read (
events(limit + 1), one probe row past the bound). The crew-log and workflow streams each make one pass over their entries parsing only the time, into adeque(maxlen=<bound>)(_newest): an entry that falls off the front and an entry whose time does not read are counted and never kept, and only the kept entries have their data scrubbed and rendered.events_from_registryhands the run's event objects over as they are, so a run with 1,000 events costs the view 200 data reads and no conversion.Items sort by
(time, stream order, the stream's own sequence), so a tie is deterministic. An entry whose time cannot be read is not placed; it is counted in its stream'sdropped.The workflow stream is the run's events, not one call's. The call number in a
workflow:<run>:agent<N>row id is a 1-based counter in the agent pool, and an event'scall_indexis a 0-based counter in the runner. They count different things, so no event can be attributed to one row. Every event of the run is shown with its type and data, so anagent_*event shows theagent_idit is required to carry and a run-level event (log,phase_started,budget_update,approval_requested,run_*) shows none; a sibling call's events appear beside this call's.A stream that cannot be read is reported, not dropped. Each stream carries a status (
ok,absent,truncated,unavailable) and a closed reason (no_record,not_retained,not_applicable,tail_limit,scan_limit,kept_limit,read_failed,no_source), in a## Streamslist at the end of the markdown. A failing stream does not fail the others, and an unreadable stream never renders as an empty one. The store read of the row itself is the one error that propagates.Scrubbing. Every string goes through the scrubber the handlers already use for task payloads (
_scrub_valueintasks.py).render_timelinetakes it as a required argument with no default, so there is no path that renders unscrubbed text, and the module defines and imports no scrubber of its own. Before anything is encoded, every leaf and every mapping key of an event's data, at any depth, is scrubbed as the text it holds (bytes decoded as UTF-8, any other object throughstr), becausestr,reprand JSON each escape a newline and a multi-line credential then does not match. It runs before anything is flattened or cut, so a credential is matched whole and a value cut atVALUE_MAX_CHARScannot leave a prefix no pattern recognises, and again on every rendered line, which covers a damaged store'skindortype.Two lookups outside the timeline module.
child_recordincrew_log/resolve.pyis a read-only sibling ofunit_holding_child. It resolves the slot's units the same way (crew_log_units(..., strict=True), so the permanent-delete exclusion applies, newest first,UnitSearchFailedwhen the store cannot be read), but it searches thesubagentsfold state rather than its render. The state keeps a child whose card was dismissed, while the render leaves it out because the panel draws only the cards the user kept.unit_holding_childis unchanged: the dismissal writer must not find a row it already cleared.crew_log_slots_forindashboard/chat_utils_slots.pylists every slot name a crew-log writer may have recorded for a session key, with no dependence on an open tab: the live tab first, then the channel transcript stem (slack_<ts>, whichmessaging/dispatch_crew_log.pyrecords), or for a cron key its per-run tab, its transcript stem and the job's owncron-<job>tab. A dispatch past the fold's retain cap has no row to place, and is reported asnot_retained.Docs. A "Task timeline" section in
docs/system-specs/modules/taskq.md, the route in the feature map's Endpoints column, and one bullet in the task-routes list ofdocs/system-specs/modules/learn-cron-dashboard.md.Backwards compatibility
Compatible: one GET route is added. The five existing task routes answer byte for byte as on
mainfor one fixed store (pinned below), the route table gains exactly this one entry, and no function body intasks.pychanges (three docstring hunks and the added handlers).Removes nothing: no route, key, field or kind is removed, renamed or hidden.
Tests
Rebased onto main at 0c0dd82 (2026-11-09). The three conflicts were text-only: the
handlers/tasks.pymodule docstring, one bullet intaskq.mdand one row in the feature map. The new module, the handler, the route and the tests are byte for byte as before. The only addition is a# flake-ok: a fake log clock, no waittag on theticksfixture'snow_mspatch, because the K19 ratchet reads the_mssuffix as a wait. On this head,test_taskq_timeline.pywith the task-route, taskq, facade-guard and spawn-audit neighbours (13 files) passes 615 tests, three runs in a row (-n0,-n 4,-n 4). The merge onto main at 3987f3a is clean.Dismissed and unretained children (review round on 5bed177). The crew-log stream now finds a child through
child_recordincrew_log/resolve.py, which searches each slot unit'ssubagentsfold state, not its render. The state keeps a row whose card was dismissed.unit_holding_childis unchanged, because the dismissal writer must not find a row it already cleared. A dispatch past the fold's retain cap is reported asabsent (not_retained)rather thanno_record. New tests:test_a_dismissed_childs_entries_are_still_served_in_order,test_a_dispatch_the_fold_did_not_retain_is_reported_as_not_retainedandtest_a_child_in_a_permanently_deleted_conversation_is_still_not_found; the first two fail on 5bed177. On head fd57d33, the timeline tests with the task-route, taskq, crew-log resolver, facade-guard and spawn-audit neighbours (21 files) pass 992 tests, three runs in a row (-n0,-n 4,-n 4). The merge onto main at d0e911b is clean.Parents with no open tab (review round on fd57d33). The crew-log slot no longer depends on an open dashboard tab.
crew_log_slots_forindashboard/chat_utils_slots.pylists every name a crew-log writer may have recorded for the parent: the live tab first, then the channel transcript stem (slack_<ts>, which the channel dispatcher records), or for a cron parent its per-run tab, its transcript stem and the job's owncron-<job>tab. The reader tries each name in order. Twelve new tests fail on fd57d33, including end-to-end reads through the real handler for a Slack parent, a cron parent and a per-run cron parent. On head c6b02da, the timeline tests with every file that touches the task route, the taskq timeline, the crew-log resolver or the slot helpers (42 files) pass 1744 tests, three runs in a row (-n0,-n 4,-n 4). The merge onto main at 6259ac7 is clean.The facade's type-checker list (CI on c6b02da).
test/test_chat_utils_facade.pyfailed on CI.crew_log_slots_forreadstranscript_stem, whichchat_utils_slots.pyimports fromkiro_crew.history_filesat module level, so thechat_utilsfacade serves that name too, and the facade'sTYPE_CHECKINGblock must name every served name from its home module. The block names it there, beside thekiro_crew.historynames it already lists. No other line changes.test_every_name_served_from_outside_the_family_is_visible_to_type_checkersfails on c6b02da and passes here. The run's other red,test_the_lazy_imports_stay_inside_the_functions_that_need_them, came from main and was re-pinned there by #34010. On head 0757b9b, merged locally onto main at fd5d9ef, the timeline, facade, crew-log, task-route and server-composition tests (94 files) pass 3665 tests, andmypy src/kiro_crew/reports no issues.In short: 137 cases in the new
test/test_taskq_timeline.pyfail at import onmainand pass here, including a credential planted in each stream and a route test that refuses a non-owner before the row is read. Size: 760 added source lines (589 of them the new module, whose only caller is this route) and 1,708 test lines; the module stays whole because splitting it would leave it without a caller.Red on
main(detachedorigin/main, the test file copied in, imported from that checkout's ownsrc, 3 runs):Green on this branch: 137 passed at
-n0, three passes; 212 passed at-n 4 --dist loadgroupbesidetest_api_tasks.py,test_dashboard_handlers_lazy_tasks.py,test_taskq_startup.pyandtest_chat_utils_facade.py.What each group locks in:
test_the_merge_orders_by_time_then_stream_then_the_streams_own_order, andtest_a_concatenation_of_the_streams_is_not_a_timelinefails a view that appends the streams instead of merging them.CREW_SCAN_MAX, entries past a kept bound and entries without a readable time are each reported on the result and in the markdown, while the other streams still render.test_a_long_run_is_bounded_before_any_event_is_converted_or_renderedgives the registry adapter a run of 1,000 event objects that count theirto_jsoncalls anddatareads: zero conversions, at mostWORKFLOW_EVENTS_MAXreads,truncated (kept_limit)with 200 kept, and two events without a readable time, one outside and one inside the kept window, both counted as dropped;test_a_stream_renders_only_the_entries_it_keepshands the crew-log and workflow streams 1,000 entries each and counts the data mappings the scrubber is given (exactly the bound);test_the_registry_adapter_hands_the_runs_events_over_in_placepins that the adapter copies nothing.test_a_credential_in_any_stream_never_reaches_the_outputplants a credential in each of the three streams as a value, a nested value, a key block and a nested key block;test_a_bytes_pem_is_redacted_before_any_encoding_escapes_itplants an unterminated bytes PEM as a value, inside a mapping, inside a list, as a nested key and as a top-level key on each stream;test_a_credential_cut_by_the_line_bound_is_redacted_before_the_cut,test_a_credential_in_a_label_is_redactedandtest_a_credential_in_the_rows_own_fields_is_redactedcover the cut, the labels and the row fields;test_the_renderer_has_no_default_scrubberpins thatscrubis a required argument;test_the_renderer_uses_the_scrubber_it_is_given;test_the_route_scrubs_what_the_store_holdsruns it through the real handler and a real store.test_the_reader_returns_only_the_childs_subagent_entries_in_order, a child dispatched before a reset found in the older unit, an absent child reported absent, a failing unit search reported unavailable,test_the_scan_window_starts_at_the_childs_dispatch_not_at_the_top_of_the_log, andtest_a_real_log_and_a_real_row_merge_end_to_end.test_a_non_owner_is_refused_before_the_row_is_read(an app token, a non-owner user, no claims; the store read is counted and stays at zero),test_the_configured_owner_passes_the_gate, 404 and 503 each with acode,test_reading_a_timeline_changes_nothing, andtest_the_lazy_wrapper_calls_the_real_handler.test_every_existing_task_route_answers_byte_for_byte_as_beforecompares eight captured responses of the existing routes with the live handlers, andtest_the_task_routes_are_the_old_set_plus_one_getpins the route table.test_the_timeline_is_a_read_only_leaf_with_no_scrubber_of_its_own,test_the_timeline_makes_no_mutating_call_and_never_opens_a_file,test_the_crew_log_is_reached_only_through_its_read_surfaceandtest_timeline_py_is_the_only_reader_added_and_the_route_the_only_caller.Neighbours run in one process at
-n0: the route-table, error-code, call-site-auth, composition and client-contract suites,test_api_tasks.py,test_overload_integration_glue.py,test_taskq_startup.pyand the taskq store, reconcile, admission and runner-adapter suites (593 passed). The wait-discipline, flake-pattern, pid-reader, kill-chokepoint, spawn-audit, tmpdir-helper and dir-fd ratchets pass at-n0(175 passed). The new file followed bytest_taskrunner_atomic_persistence.py,test_taskrunner_execution_capture_async.py,test_unattended_slot_guardrails.pyandtest_wheel_apply.pyin one process passes (234 passed), because the new tests patch module attributes.mypy src/kiro_crew/, black, isort and flake8 on the touched files,scripts/check_agent_sdk_boundary.py, the comment-history, brand and feature-map gates andscripts/docs-lint.shpass.Manual verification
N/A — no UI. The route is exercised through the real handler, a real
TaskStoreand a real crew log intest_taskq_timeline.py. Not measured: a read of a long-lived session's log on a gateway with a large real history. The crew-log side reads one window from the child's dispatch to the end of its unit, off the loop, with memory bounded byCREW_SCAN_MAXrows.Screenshots / video
N/A — the change adds an API route and no user-visible surface; no file under
website/changes.Related Issues
None describes this gap. #13628 asks for a tool-call and cost view on the Subagents card, a different surface that this change does not provide.
Pattern harvest
Not generalizable: this adds a feature, so there is no fixed defect whose class a rule could stop.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement