Repository navigation
feat(subagents): per-chat agent-queue priority (low/medium/high) - #15543
Pearcekieser wants to merge 1 commit into
Conversation
|
Intent: Let the dashboard owner give each chat a Low, Medium or High agent-queue priority, so that when sub-agent spawns queue at the cap, a higher-tier chat's waiting spawns start before a lower tier's, with today's round-robin kept inside a tier. |
8c0a8a2 to
0aaeb5e
Compare
|
Pushed
The queued runs on the old head could not be cancelled from the fork; please ignore them. |
UX Review (Opus 5.5, fork) — ✅ PASSUX-level review of UX-Verdict: PASS No blocker found. The screenshots show every added control and state, but no first-time reader has seen them, because this fork lane has no blind read. A maintainer can push the branch to this repository to get one. Notes
[UX-REVIEWED] baf22c5 Description read[DESCRIPTION-READ] 91dbd1b5d9391f5f769e5b1e5ad34855a8d04d5bd1bd04495839073f37ad2506 That sha256 names everything this verdict read: the PR description, plus the 10 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 |
Design Review (Opus 5.5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: tiers are off unless someone sets one, so the default pick order stays the same. The tier lives in memory only, which a revert or a gateway restart undoes completely. Notes
[DESIGN-REVIEWED] baf22c5 Description read[DESCRIPTION-READ] 64039ee66be44fd5a5168deb209ad699af14e862e76f7555046d005b53ac5ec9 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, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. Every chat defaults to Medium, so dispatch order stays the same unless the owner picks a tier. Two small surfaces are second spellings or have no consumer outside the module. Notes
What this change shipsInventory (10 items) — 8 justifiedIntent: let the person push one chat's waiting sub-agent spawns ahead of others, or park a chat behind them, when spawns queue at the cap. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] baf22c5 Description read[DESCRIPTION-READ] 7fd1917daa223e208eb6f5174ad8a1f7f0e4115fe8f82bc5782c676f2f6d0f87 That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review (fork) — ✅ no blocking findings (all downgraded on adjudication)Reviewed Opus 5.5 adjudication downgraded every blocking finding. Downgraded: the remedy each one needs is disproportionate to the harm it prevents. Adjudication downgraded all 1 blocking finding(s): the remedy each one requires is disproportionate to the harm it prevents. Review detailsBLOCKING -- src/kiro_crew/subagent_manager/admission/taskq_bridge_window.py:151 -- Child-only refill repeatedly displaces High roots with Low children
Adjudication (Opus 5.5) — is blocking on each finding proportionate?F1 — LOW harm, and it needs a non-default config. The High root is only evicted when the window is full with no spare entry: the eviction count is computed at |
|
|
|
|
|
|
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed |
0aaeb5e to
7070b2a
Compare
|
Rebased: main moved in modules this PR imports ( |
|
|
|
|
|
|
|
|
HOLD at a04aaf3, reserved for maintainer sign-off. Our r131 items are answered. Each deferred item now has its own issue, Pearcekieser#59 to #64, linked in the description's Follow-ups section, and each one names the file and the fix. The UX note on the unconfirmed notice moved to #64. This head is a rebase of 20a5266 with the same patch apart from two What still blocks: the new owner-only AI findings judged non-blocking:
I read the source and CI; I did not run any PR code. — crew-pr-reviewer (r134) |
|
|
|
|
|
The Fork GPT 6.1 Review lane never started for head 5637b1c, so PR Readiness still waits on it; it needs a re-run. |
iamwhatever
left a comment
There was a problem hiding this comment.
Requesting changes (issue required) at 1edf1c9.
The Shared Crew fixes since our r134 read correctly. set_lane_resolver now marks the automation principal's lane untiered (admission_gate.py#L1711). A chat charged to automation for one turn keeps its stored tier, and that tier is dormant until the person's next turn. Opus and GPT have no blocking findings, and every check is green.
What blocks:
- A deferral without an issue. Your disposition on GPT span=9cd791b15d8b (comment) moves "re-read the tiers after each awaited step and repeat the root refill" to the follow-up PR "with Pearcekieser#59". #59 covers the system-lane eviction exemption, and it does not mention this. Add the item to #59's body, or open its own issue and link it in Follow-ups.
- Merge conflict. The branch conflicts with main again in
website/src/i18n/en.context.json. - Maintainer sign-off. The owner-only
PATCH /api/chat/slots/{slot}/queue-priorityroute decides who may reorder other chats' spawn waits, so a maintainer has to approve it. That maintainer should also confirm that follow-up issues on your fork are acceptable.
AI findings judged non-blocking:
- Design note: under Shared Crew a tier picked in one chat reorders all of that person's chats, and the caption does not say so. The description states the rule, so only the caption wording is missing. The maintainer may want to weigh this at sign-off.
- Design note on
_floor_fit_idsand First Principles item 6 (the eviction ceiling): you answered both, and #62 tracks the fold. - UX notes: attachment-07 is a stale screenshot, and "gateway" is a wording nit. Neither changes what a user sees in the code.
I read the source and CI; I did not run any PR code.
— crew-pr-reviewer (r137)
|
note (non-blocking): reply to iamwhatever's r137 on 1edf1c9.
|
resolution: removed -- the absent-untiered exemption in the eviction ceiling is gone and eviction under a ceiling runs in tier order |
iamwhatever
left a comment
There was a problem hiding this comment.
Requesting changes at e29fa44f9e69db21b4534d70e6295890d55d4910.
The r137 items are answered: the refill-snapshot deferral now has its own issue (Pearcekieser#66, linked in Follow-ups), and the branch merges cleanly with main.
What blocks:
- The tiered eviction drops a Medium head while cron and hook lanes keep spares. The Opus lane raised this on this head and I confirmed it in the code. Once any chat is at Low or High,
_refill_evict_ceilinggives a Medium absent lane a ceiling of rank 1 (L269-L282)._evict_for_lanesthen visits the groups in tier order and drops a head in the first group with no spare, before it looks at the untiered group, which sits last (L584-L616). With one Medium lane A in the window next to severalsystementries, A loses its only head whilesystemkeeps its spares, and the next pass does the same to the next Medium lane. Cron and hook spawns then hold most of the window, which breaks the rule the docstring states. Smallest fix: under a ceiling, look for a spare across every group first, and use tier order only to pick which spare goes, or which head goes when no group has one. Please add a test with this window shape. - Maintainer sign-off. The owner-only
PATCH /api/chat/slots/{slot}/queue-priorityroute decides who may reorder other chats' spawn waits, so a maintainer has to approve it. That maintainer should also confirm that follow-up issues on your fork are acceptable.
CI is still running on this head (Backend Tests, Frontend Tests, E2E and Build Desktop).
AI findings judged non-blocking:
- First Principles item 6: the
automation_principalkeyword onset_lane_resolveris used only by tests. It is a simplification. - Design note:
_floor_fit_idsis kept in sync at four sites. Pearcekieser#62 tracks folding it. - UX notes: "gateway" in the caption and a stale
menu-save-failed.png. These are wording and evidence nits; the code renders the separator.
I read the source and CI; I did not run any PR code.
— crew-pr-reviewer (r145)
resolution: narrowed -- spares are taken exactly as before the tier work; only the no-spare head drop follows tier order |
|
note (non-blocking): reply to iamwhatever's r145 on e29fa44.
The First Principles note (drop the test-only |
resolution: narrowed -- "not saved" now only for a 4xx the route answers before it writes; every 5xx and transport failure reads as unconfirmed |
|
Hold at 05b63af for a maintainer. The eviction defect from our r145 review is fixed: What still needs a maintainer:
AI findings judged non-blocking:
— crew-pr-reviewer (r147) |
resolution: narrowed -- chat tiers are off while a Shared Crew lane resolver is installed, so no principal lane ever carries a tier |
resolution: removed -- the tier-aware refill eviction is gone and eviction is tier-blind as on main |
|
bolichen97
left a comment
There was a problem hiding this comment.
Maintainer note on 8b23010. All 100 checks pass. This is a new user-facing feature (a session-menu submenu, a new route and a scheduler change), so I'm giving a design brief for the owner's sign-off rather than approving.
On the open change request from 11-04 (e29fa44): point 1 is gone with the design change. The refill eviction (_evict_for_lanes) is now tier-blind, so it no longer drops a Medium lane's only head while system lanes keep spares. Tiers act only on which waiting lane's head is picked and fetched first. Point 2, sign-off on the owner-only route, is what this brief is for.
Design brief:
- What it does: each chat gets a sub-agent queue tier, High, Medium (the default) or Low. A pick considers only the waiting chats in the highest tier present, and the existing weighted round-robin runs inside that tier. The tier is set from the session menu through the owner-only
PATCH /api/chat/slots/{slot}/queue-priority, which refuses app and crew-member callers with 403 before looking the slot up. It lives in gateway memory only, so every chat is Medium again after a restart. - Pros: a person can push one chat's sub-agents through, or park a background chat, without stopping other chats. With every chat at Medium, dispatch order is unchanged, and cron and hook spawns keep their place.
- Cons: Low has no aging, so a busy High chat can hold Low spawns back indefinitely, which the PR states as a non-goal. Tiers are off under Shared Crew admission (issue #67 on the author's fork). The tier is forgotten on restart.
- Tech debt: small. There is one leaf module (
queue_priority.py), a tier filter inLaneScheduler.pickand a resolver hook._floor_fit_idsis kept in sync at four sites, tracked in issue #62 on the author's fork. Follow-ups are tracked on that fork, not in this repo.
The sign-off is the owner's.
|
note (non-blocking): one correction to the tech-debt line, for the sign-off.
|
Each chat can set its agent-queue priority from the session menu. When the
gateway is at its sub-agent cap, waiting spawns of a High chat start before
any Medium one, and Medium before Low; the weighted round-robin still runs
inside a tier. Nested spawns inherit the root chat's lane and so its tier.
Picks under the child reserve ignore tiers, and the system lane (cron, hooks)
is never filtered out by a tier.
- taskq.lanes: strict priority tiers above the weighted round-robin
- SubagentManager.set_lane_priority_source; DashboardState installs
lane_queue_priorities (tiers stored per session key, in memory only)
- PATCH /api/chat/slots/{slot}/queue-priority (owner-only), projected on the
slot row; never written to the transcript, so every chat is Medium again
after a restart
- Tiers are off while Shared Crew's lane resolver is installed (409
queue_priority_shared_crew, row reports null)
- Session menu: Sub-agent priority radio submenu, 12 locales
|
Holding my approval on this one for now, and I have turned off auto-merge. The work is careful and the scheduler change reads correctly. My concern is scope: per-chat sub-agent priority feels like a personal workflow knob more than something most users need, and it adds surface we would carry for a long time (the Before we take it, I would like to see the same need from more users. Thanks for sticking with all the review rounds. |
Code change approver recommendation: A person should decideWhy: the decider thinks the change is probably fine but estimates a 15% chance that this change introduces a defect, above the 12% limit for approving on its own. I'd approve this PR as it stands, with moderate confidence. Each chat gets a Low, Medium or High tier, held in gateway memory only and settable only by the dashboard owner. The tier is applied only when a top-level (root) start is free. Starts under the child reserve ignore it, as does the children-only refill when only reserve capacity is free. The system lane (cron, hooks, heartbeat) is never filtered out by a tier, and with no tiers set the order is exactly main's. I traced every caller of the scheduler and the tier source. The tier snapshot is read on the event loop and passed explicitly to the refill fetch that runs on the task store's writer thread (via the An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
Problem / Motivation
Goal: Let each chat set its agent-queue priority to Low, Medium or High, so an urgent chat's sub-agents start first when spawns have to wait.
When the gateway is at its sub-agent cap, new spawns wait in a queue. Today every chat gets an equal turn in that queue (round-robin across chats, FIFO inside one). There is no way to say "this chat matters more right now": a long background sweep in one chat delays the spawns of the chat the person is actively waiting on, and a low-value chat competes on equal terms with everything else.
Why it matters
People run many chats at once, and the sub-agent cap is often the bottleneck. Without a priority knob the person has to stop or close other chats to get one chat's work through. A per-chat tier lets them push one chat forward, or park a background chat behind everything else, without touching anything that is running.
Not a goal
What changed (motivation → approach → change)
taskq/lanes.pySubagentManager.set_lane_priority_sourcePATCH /api/chat/slots/{slot}/queue-prioritysrc/kiro_crew/queue_priority.py,src/kiro_crew/taskq/lanes.pyLaneScheduler.prioritiesand the tier filter inpicksrc/kiro_crew/subagent_manager/fairness.pylane_priorities()feeds both scheduler balances (taskq_bridge.py), and the refill fetch brings higher-tier lane heads into the dispatch window firstsrc/kiro_crew/subagent_parts/set_lane_priority_source(config_surface.py, bound inmanager.py, listed inadmission_surface.py)src/kiro_crew/dashboard/state.pyslot field +lane_queue_priorities;chat_handlers.pyroute;routes/chat.py,chat.pyregistration;slot_projection.pyrow fieldwebsite/src/components/QueuePrioritySubmenu.tsx,SessionActionsMenu.tsx(the radio itemsui/context-menu.tsxalready exports)website/src/hooks/,website/src/api/,website/src/types/useSessionActions.tssetQueuePriority;chatOrganization.tssetSlotQueuePriority;index.chat.tsQueuePriority, re-exported byindex.tswebsite/src/i18n/locales/*.json), translator context for "Low" (en.context.json)website/src/test/stubRadioMenu.tsxradio-menu stand-ins for happy-dom;ApiClient.refactor.surface.test.tskey orderdocs/system-specs/modules/taskq.md,system-specs/modules/subagent.md,feature-map/README.mdtemp-screenshots/agent-queue-priority/The queue already groups waiting spawns into one lane per chat, and a sub-agent's own spawns inherit the lane of the chat that started the tree. A tier per lane is therefore the smallest change that turns the existing fair queue into a priority queue:
LaneScheduler.pickkeeps only the contending lanes of the top tier, and lower tiers neither win nor gain round-robin credit while a higher tier has work. Tiers apply to root picks only: a pick under the child reserve, and the children-only refill that feeds it, ignore them, so a High chat can never hold back the child an already-running tree is waiting on. With every chat at Medium the order is exactly today's.Strict tiers were chosen over larger lane weights because weights only change the share, so a Low chat would still take regular turns, which is not what "Low" promises. The tier is pulled from the dashboard on each pick (
DashboardState.lane_queue_priorities, keyed by the session each chat's turns run on) instead of being pushed into the manager, so a restored, forked or closed chat cannot leave a stale entry behind. A failing source reads as all Medium.The route refuses app and crew-member callers with 403 before it looks the slot up (so the answer does not reveal whether a chat exists), because a tier reorders other chats' waits and an agent must not raise its own chat above the person's. The value is validated against the three names and stored in memory per session (
DashboardState._session_queue_priority, keyed by the session the chat's turns run on), written for every live session on the chat's dispatch lane. Each read maps the sessions to their current lane, so every slot on a lane reads the same tier, including a slot that joins later. With no Shared Crew lane resolver installed, a lane is one session orsystem, so a tier is exactly per chat. While Shared Crew admission is on, chat tiers are off: the resolver files a session under the person whose turn ran last, so a stored tier would rank that person's whole lane. The dashboard then reports no tier for any lane, every row carriesqueue_priority: null(the menu entry is hidden), and the route answers 409queue_priority_shared_crewand stores nothing. The tier is projected on the slot row and the one-row slot patch. A cron- or hook-bound chat has no tier, judged from its session key alone. A cron- or hook-bound chat: its row carriesqueue_priority: null, the menu entry is hidden, and the route answers 409queue_priority_system_lane.lane_queue_prioritiesreports only lanes that still have a live slot. Each PATCH also drops the stored tiers of sessions with no live slot, so the map never holds more entries than there are live slots plus the one being set. No tier is written to or read back from the chat's metadata line, because that line is a file the agent's own tools can write. A restored tier would let a prompt-injected agent move its own chat past the owner-only route: plant High, or rewrite an owner's Low to Medium and wait for a crash restart. This is the same rulejev_routefollows. After a restart every chat is back at Medium, and the submenu caption says so. The submenu stays open after a pick, so the moved check and any error notice are visible. The menu is not optimistic. It sends one PATCH at a time per chat, so the server applies picks in order, and the row moves only when the gateway'squeue_priorityslot patch arrives, which the route pushes to every live slot of the lane once the tier changes. There is no local tier to roll back or reconcile, so an older request, another dashboard's pick or a lost answer cannot put a stale tier on the row. A failure shows an in-menuErrorNoticewith its agent hand-off (a separator keeps the hand-off apart from the tiers), which carries the request's report (endpoint, status and error code), and localized lines, never the gateway's English error text. A gateway refusal (any 4xx, all answered before the route writes) says "The priority wasn't saved. Try again." A 5xx, which a proxy can return after the gateway applied the pick, or a transport failure may have committed, in which case the slot patch still moves the row, so it says "Priority not confirmed" / "The gateway didn't answer. Pick the priority again to make sure it's saved." Only the slot's latest pick may show a notice, so an older failure never contradicts a newer pick. Thesystemlane (cron, hooks, heartbeat) has no chat to raise, so the tier filter never drops it: it takes part in every tiered pick and keeps its weighted share beside the top tier, so a High chat that keeps spawning delays waiting automation by at most one round. That bound is about picks among rows already in the dispatch window. Which rows are in the window is main's unchanged refill: with a window of one row, the child-only refill can replace a cron root with any chat's nested child on each pass, with or without tiers. Against Low chats alone it still ranks Medium. The dispatch-window refill fetches the absent lanes' heads in tier order, so a High lane's head enters the window before a Low one's. Each refill reads the lane tiers once and hands that one mapping to the fetch. While a root slot is free, the child-only refill that follows fetches the same way; it runs untiered only when the free capacity is reserve-only. The refill eviction stays tier-blind, exactly as on main: it takes spares first and then a lane head, whatever the tiers. A tier-aware eviction was tried in earlier rounds and removed, because keeping higher-tier entries let a High backlog evict the only windowed cron head on every pass. The cost is that, when more lanes wait than the window has places (64 by default), a High root can start one refill late. The per-lane memory share (lane_share_holds) holds a start back only for a waiting lane on the same or a higher tier, or for the system lane, which has no tier, so a High chat's start never gives way to a Low chat's memory wait but still gives way to a waiting cron or hook spawn. The submenu sits in the bottom group directly above "Turn time limit", the other run-behaviour submenu. The feature map row and thetaskq.md/subagent.mdspecs describe the tiers.Backwards compatibility
Compatible: the default tier is Medium, and with every lane at Medium the dispatch order is unchanged. Older transcripts carry no
queue_prioritykey, and a key written into one is ignored. The slot row gains one optional field.Tests
test/test_fairness_lanes.py: with no child reserve, a dispatch window of 2, a High backlog and a queued nested child, a waiting cron spawn still starts before the High backlog drains; tier names normalize (unknown → Medium); the top tier wins every pick and lower tiers accrue no credit; weighted round-robin still runs inside a tier; no priorities equals today's round-robin; the refill interleave puts a High lane first; an untiered pick ignores priorities; under the child reserve a High chat does not take the reserve every pass; thesystemlane keeps its share beside a High chat and still ranks Medium against Low. Through the real manager and task store: spawns queued Low, Medium, High start High, Medium, Low; with three High spawns queued, a fresh cron spawn starts in the first round while a Medium chat still waits (this is that test's setup, not a general bound:taskq.mdnotes that a High lane can take up to 17 starts before the next automation grant, depending on the creditsystemcarries); a change reaches the next pick; a failing source keeps FIFO;lane_snapshotreports each lane's tier.test/test_chat_queue_priority.py: the route sets each tier without saving the transcript and the lane map sees it at once; a pick applies to every slot on the session and patches each; a slot that joins the session later (minted with a link, linked afterwards, or rehydrated) reports the session's tier; a cron-bound chat gets 409queue_priority_system_laneand serializesqueue_priority: null;lane_queue_prioritiesdrops lanes with no live slot; with a Shared Crew lane resolver installed, a High tier set on a channel chat never reaches the lane of the next person who posts there (the source reports no lane and the row is null), the route answers 409queue_priority_shared_crewand stores nothing, and a non-owner still gets 403 first; reports and audits no-op changes, rejects bad values (including"HIGH", bools and lists), 404s an unknown slot, and 403s app, non-owner and crew-member callers; nothing is written by a save and every restore starts at Medium; a tier written into the transcript is ignored; the dashboard installs itself as the source.test/test_chat_slot_facade_contract.py: the projected slot row carriesqueue_priority.test/conftest.py: the autouse fixture that clears an inherited Shared Crew admission service also clears the lane resolver that service installs, so a test that leaves one behind cannot turn tiers off for later tests on the same worker.test/test_json_object_body_guard.py: the new route's body read is registered with the default cap for bounded control fields.website/src/components/QueuePrioritySubmenu.test.tsx: both menu families show the caption and list the three tiers, Medium is checked when unset, a pick is reported, every pick is sent once, including the tier that is checked, the failure notice carries the agent hand-off described by the notice, and a given heading replaces the failure title.SessionActionsMenu.cov80.test.tsx: the entry sits directly above Turn time limit and is hidden forqueue_priority: null.website/src/hooks/useSessionActions.cov80.test.tsx: a pick is sent to the server and the row follows the gateway's slot patch, a refusal shows the localized retry line rather than the gateway's text and leaves the row, a transport failure says the priority is not confirmed, a refusal keeps another dashboard's slot patch, a refusal after a lost answer and a later save keeps the saved tier, and an older failure says nothing once a newer pick is in flight; picks for one chat are sent in order; a failure is exposed for that chat and cleared by the next success.QueuePrioritySubmenu.test.tsxrenders the error notice and hand-off item only when given an error, and a pick keeps the menu open.test/test_channel_slots.py: a re-surfaced channel chat whose metadata names Low or High starts at Medium.website/src/components/SessionActionsMenu.cov80.test.tsx: the menu shows the slot's tier and wires the pick to that slot.Manual verification
On an isolated gateway built from this branch (
kiro_crew.testing.harness.spawn_feature_gateway("minimal")), right-clicked a chat, opened Sub-agent priority, and picked High. ThePATCHanswered200 {"ok": true, "queue_priority": "high", "changed": true}, the reopened submenu showed High checked (aria-checked="true"), andGET /api/chat/slotsreturnedqueue_priority: "high"for that chat and"medium"for the others.Screenshots / video
Right-click menu on a chat, default state (Medium checked):
After picking High:
A refused pick: the menu stays open, Medium stays checked, and the notice shows the localized retry line with the agent hand-off.
A pick whose PATCH got no answer shows the same notice with the title "Priority not confirmed", and the previous tier stays checked until a slot patch says otherwise.
The first two stills were rendered from 75d2181e71 and the refused-save still from 920771b, all with stubbed API responses and show the shipped caption "Higher-priority chats' waiting sub-agents start first. Resets to Medium on gateway restart."
Related Issues
no linked issue: feature requested directly by the maintainer's team.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Follow-ups
Review items deferred from this PR, one issue each:
queue_lane_offrom the state facade and drop the route's local copy.normalize_queue_priorityintopriority_rank.