Skip to content

fix(llm): bound background one-liner calls - #18908

Merged
iamwhatever merged 2 commits into
kirodotdev:mainfrom
javenciu:fix/background-oneliner-calls-are-bounded
Oct 11, 2026
Merged

iamwhatever merged 2 commits into
kirodotdev:mainfrom
javenciu:fix/background-oneliner-calls-are-bounded

Conversation

@javenciu

@javenciu javenciu commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Four background one-liner calls pass no timeout to run_bg_oneliner: the session title (src/kiro_crew/dashboard/chat_title.py, _generate_title_via_kiro and _generate_refreshed_title), the session summary (src/kiro_crew/dashboard/chat_summary.py) and link labels (src/kiro_crew/dashboard/chat_nav.py). Measured with a stub background session:

  • A call on a silent backend has no bound of its own. It waits until the session handle's watchdog gives up, after 600 s, or 1800 s while the handle reads the backend as waiting on the model. The whole time it holds a background session.
  • The watchdog ends that turn with an ordinary EVENT_COMPLETE (stop_reason="stale_recover"; a turn that reaches the turn ceiling ends with "timeout"). run_bg_oneliner stops at any EVENT_COMPLETE and returns the text so far, so a cut-off answer was kept as the title: 'Fix the cron history leak in remove'.
  • Five identical link-label requests started five calls and held five background sessions.

Goal: a background one-liner ends within a stated time, a turn the backend never finished is a failure rather than an answer, and identical link-label requests share one call.

Why it matters

Each waiting call holds a background session, for up to 30 minutes on a stalled backend. Link-label requests stack up with no limit, and a truncated title is shown and kept.

Not a goal

  • Other run_bg_oneliner callers. Most already pass a timeout (folder icon and folder suggestion 30 s, suggestions and cron contradiction 60 s, tips 90 s).
  • Changing the session handle's watchdog windows.

What changed

  • STOP_REASON_TIMEOUT = "timeout" (new, src/kiro_crew/acp/types.py) names the stop reason the session handle gives a turn that hit the turn ceiling. The handle still writes the literal; the constant gives the readers one name for it.
  • _raise_if_unfinished (new, src/kiro_crew/llm_helpers.py) runs on run_bg_oneliner's EVENT_COMPLETE. When the stop reason is STOP_REASON_TIMEOUT or STOP_REASON_STALE_RECOVER, it raises AcpTimeoutError with the partial text and transient=False, so the caller's existing failure path runs: no title, the current title stands, no summary, no labels. This can switch to the shared unfinished_turn_error of the open "treat a turn the backend never finished as a failure" change once that lands; the two do not overlap (git merge-tree is clean both ways).
  • _raise_if_unfinished imports those three names at call time from kiro_crew.agent_sdk.drivers.acp_vocab, the module that already gives application code the stop classes and the session-start timeout, and that module now also exports them. llm_helpers.py keeps its 5 ACP-layer imports in .github/agent-sdk-boundary-baseline.txt, which scripts/check_agent_sdk_boundary.py holds shrink-only. Importing them from kiro_crew.acp made the count 7. Adding them to llm_helpers.py's existing module-level kiro_crew.acp imports keeps 5, but it rewrites those two lines, and the gate also refuses an ACP import on a line the change adds.
  • Timeouts at the call sites, with the reason stated where each is defined:
    • _TITLE_TIMEOUT_SECS = 30.0 for both title calls, the same 30 s as the folder icon and folder suggestion one-liners.
    • _LINK_SUMMARY_TIMEOUT_SECS = 30.0 for link labels.
    • _SUMMARY_TIMEOUT_SECS = 60.0 for the session summary. Its prompt carries the bounded transcript, so it gets the 60 s the suggestions and cron contradiction one-liners use.
  • _shared_link_summaries (new, chat_nav.py): the link-label route awaits a call shared through _LINK_SUMMARY_INFLIGHT. An identical request awaits the running call, behind asyncio.shield, so a request that goes away does not cancel it for the others. A done-callback removes the entry when the call ends, however it ends. At most _LINK_SUMMARY_INFLIGHT_MAX = 8 distinct link sets run at once; a request past that gets the route's existing fail-soft answer, 200 with no labels.
  • _bounded_link (new, chat_nav.py) cuts a link to the part the prompt reads: the url to _LINK_URL_MAX = 500 characters and the stripped context to _LINK_CONTEXT_MAX = 300, the limits _build_link_summary_prompt already applied, now named once and used there. The in-flight key and the shared call's input are built from these bounded links, so an entry holds at most 800 characters per link, for at most 20 links per request and 8 entries, however large the request body is (the dashboard accepts up to 60 MiB). Labels are positional, so each waiter's labels line up with its own links, and requests that agree on the fields the prompt reads share a call because they send the same prompt. The one prompt change: a context whose 300-character cut ends in whitespace drops that whitespace, so applying the cut twice gives the same link.

Backwards compatibility

Compatible: the routes and response shapes are unchanged. A title, summary or link-label call that takes longer than its timeout now fails the way a model error already does: the current title stands, there is no summary, and the frontend shows raw-URL chips. A finished turn returns its text exactly as before.

Removes nothing: every route, response field and helper stays; the title, summary and link-label calls gain a timeout, run_bg_oneliner gains a stop-reason check, and the link-label route gains an in-flight map that holds an entry only while its call runs.

Tests

  • test/test_chat_title.py, TestTitleCallBounds:
    • test_a_silent_backend_ends_the_title_call_at_its_timeout (timeout patched to 0.2 s): the call ends with TimeoutError and releases its session.
    • test_a_turn_the_stale_watchdog_ended_gives_no_title: raises AcpTimeoutError and releases its session.
    • test_a_finished_turn_is_still_the_title: the control.
  • test/test_chat_nav.py, TestLinkLabelInFlight:
    • test_identical_requests_share_one_call: 5 concurrent identical POSTs to the real route start 1 call, all 5 get the same labels, and the in-flight map is empty afterwards.
    • test_a_single_request_is_not_delayed: the control. One request completes with one session acquired and released; a request held behind a join would show as a second acquire or a reply that never comes. No wall-clock bound is asserted.
    • test_an_inflight_entry_holds_only_the_bounded_fields: a request with a 1 MiB url and a 1 MiB context; while its call runs, the in-flight key and the shared call's input each hold at most 800 characters.
    • test_two_identical_long_requests_share_one_call: the control for long links. Two requests with the 1 MiB url start one call.
    • test_labels_for_a_long_url_line_up_with_the_request: the control for the response. A long and a short link get their own labels in order, and the prompt still carries the url's first 500 characters and no more.

Red on origin/main 843abe3 (the two test files copied onto it, the new classes selected, 3 of 3 serial runs): 5 failed, 3 passed each. Three fail on the defect:

FAILED test/test_chat_nav.py::TestLinkLabelInFlight::test_identical_requests_share_one_call - AttributeError: module 'kiro_crew.dashboard.chat_nav' has no attribute '_shared_link_summaries'
FAILED test/test_chat_title.py::TestTitleCallBounds::test_a_silent_backend_ends_the_title_call_at_its_timeout - AssertionError: the title call was still waiting on a silent backend after 3 s
FAILED test/test_chat_title.py::TestTitleCallBounds::test_a_turn_the_stale_watchdog_ended_gives_no_title - Failed: DID NOT RAISE <class 'kiro_crew.acp.client.AcpTimeoutError'>

test_identical_requests_share_one_call fails on main at its counting spy, which patches the new _shared_link_summaries; the two in-flight tests (test_an_inflight_entry_holds_only_the_bounded_fields, test_two_identical_long_requests_share_one_call) fail on main by the same AttributeError on _shared_link_summaries and _LINK_SUMMARY_INFLIGHT, which proves nothing about the behavior. On a scratch copy of main with only those two names added (an empty map, and _shared_link_summaries forwarding to _resolve_link_summaries), 3 of 3 serial runs, all three fail on behavior: AssertionError: 5 background calls ran for 5 identical requests, assert 2 == 1 (two long identical requests started two calls), and ValueError: max() iterable argument is empty (no in-flight entry to bound). The three that pass on main are the controls.

test_an_inflight_entry_holds_only_the_bounded_fields, run against the first version of this change (in-flight key built from the full links), fails with AssertionError: an in-flight key holds 2097172 chars of a 2 MiB request; the two long-link controls pass there.

Green on this branch (rebased onto origin/main 843abe3): test/test_chat_nav.py and test/test_chat_title.py, 3 of 3 serial runs: 174 passed each. The 52 test files that use these modules (run_bg_oneliner, the link-label route, the title and summary generators, STOP_REASON_STALE_RECOVER), the two changed files first, run together: 4,923 passed, 1 skipped. mypy, flake8, isort, black (chat_nav.py, chat_title.py, test_chat_nav.py and test_chat_title.py are in the black baseline and were not reformatted; the other four changed files are clean), scripts/check_black_formatting.py, scripts/docs-lint.sh, scripts/check_comment_history.py (base origin/main), scripts/check_agent_sdk_boundary.py with and without --test, scripts/check_acp_frame_host_data.py, scripts/check_sync_io_in_async.py, scripts/check_lockdown_before_publish.py and scripts/check_brand_name.py all pass.

Manual verification

None beyond the tests.

Related Issues

None found. Searches for "run_bg_oneliner timeout", "title generation hang", "bg oneliner timeout", "stale_recover title" and "link summaries timeout" across PRs and issues returned nothing.

Overlap with open PRs: 31 open PRs touch the changed files. For each one, git merge-tree was run against this branch and against its base. This change adds a conflict with two PRs:

The other 29 have the same conflict set with and without this change.

Pattern harvest

Rule candidate: review-prompt
Pattern: a background model call nobody waits on that passes no timeout, and a caller that reads a turn's events itself and treats EVENT_COMPLETE as success without checking the stop reason (the session handle ends a stalled turn with the same event as a finished one).

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@javenciu
javenciu requested review from a team and KiroCrewCaptain as code owners October 10, 2026 19:09
@javenciu
javenciu requested a review from iamwhatever October 10, 2026 19:09
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Oct 10, 2026
@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 9f647c0ce75d840b3fe6323d1c62ded1d246f164 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 9f647c0ce75d840b3fe6323d1c62ded1d246f164 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check whether the frontend caches the empty labels it gets when the 8-entry in-flight cap rejects a request. If it does, those links stay raw URLs for good.

[DESIGN-REVIEWED] 9f647c0

Description read

[DESCRIPTION-READ] f639bb4012cb91030c0e981f52f09789a24852b1528a3b1edeeb955d3d302675

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — 🟡 CONCERNS

Premise-level review of 9f647c0ce75d840b3fe6323d1c62ded1d246f164 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

_raise_if_unfinished checks two stop reasons by hand when classify_stop_reason already does that job, and the new server-side link-label map repeats a dedupe the client already does.

Not justified as shipped

  • Item 4 — duplicate of acp/types.py:classify_stop_reason: it checks stop_reason not in (STOP_REASON_TIMEOUT, STOP_REASON_STALE_RECOVER), but that function's own docstring calls it "the single mapping every completion consumer uses", and acp_vocab already exports it. The check also runs for all 15 run_bg_oneliner call sites, though ## Not a goal excludes "Other run_bg_oneliner callers".
    Subtraction: replace the hand-picked pair with classify_stop_reason(...).is_success, and drop the new STOP_REASON_TIMEOUT constant (item 5) and the three acp_vocab exports added for it.
    Clears when: the check goes through classify_stop_reason.
  • Item 6 — duplicate of website/src/hooks/useChatNavigation.ts:73: react-query already shares one request per ['nav-link-summaries', batchKey] with staleTime: Infinity. The "five identical requests" case was made with a stub, not seen in the product. With the 30 s timeout, each call already ends on its own.
    Subtraction: delete _shared_link_summaries, _LINK_SUMMARY_INFLIGHT, _LINK_SUMMARY_INFLIGHT_MAX and _bounded_link (items 7–8 go with them).
    Clears when: duplicate identical requests are shown reaching the route from the real dashboard.

What this change ships

Inventory (8 items) — 3 justified

Intent: keep background title, summary and link-label calls from holding a background session for up to 30 minutes, or saving a cut-off answer. FIX.

  1. Title calls (first and refresh) give up after 30 s — justified
  2. Session summary call gives up after 60 s — justified
  3. Link-label call gives up after 30 s — justified
  4. A turn the backend never finished now fails instead of returning cut-off text, for all 15 one-liner callers — duplicate of classify_stop_reason
  5. New STOP_REASON_TIMEOUT name plus three vocab exports — one consumer, goes away with item 4
  6. Identical link-label requests share one running call — duplicate of client react-query dedupe
  7. A 9th distinct link set while 8 run gets no labels — rides along with item 6
  8. Link context drops trailing whitespace after the 300-character cut — rides along

[FIRST-PRINCIPLES-REVIEWED] 9f647c0

Description read

[DESCRIPTION-READ] 7d429ad4dc0d2f690fc46caa7d613557c85fab22e469171742842daf8606f06e

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 9f647c0ce75d840b3fe6323d1c62ded1d246f164 via the fork AI-review pipeline; updated in place on each push.

Review details

One advisory finding; nothing blocks the merge.

FINDING — src/kiro_crew/llm_helpers.py:1718 — _raise_if_unfinished imports from kiro_crew.agent_sdk.drivers.acp_vocab import (... AcpTimeoutError,) inside the function with no # circular import or import-weight comment, which breaks the advisory top-level-imports rule, whose exceptions all require a comment naming the reason → Fix: move the import to the top of the module, or add the comment that names the cycle or the import-weight reason.

[OPUS-REVIEWED] 9f647c0

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 9f647c0ce75d840b3fe6323d1c62ded1d246f164 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 9f647c0

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 10, 2026
@javenciu

Copy link
Copy Markdown
Contributor Author

The required Backend Lint & Type Check job failed on scripts/check_agent_sdk_boundary.py: the two imports _raise_if_unfinished added, AcpTimeoutError from kiro_crew.acp.client and the two stop reasons from kiro_crew.acp.types, raised llm_helpers.py's ACP-layer imports from 5 to 7 against the shrink-only baseline. The second commit, aa9c49f, moves them to kiro_crew.agent_sdk.drivers.acp_vocab, the module that already gives application code the stop classes and the session-start timeout and now also exports these three names; _raise_if_unfinished still imports them at call time. The count is back at 5, the baseline is unchanged, and the gate passes with and without --test. The names are the same objects, so nothing else changes: both test files give 174 passed in 3 of 3 runs, and the 52 neighbouring files give 4,923 passed, 1 skipped. Adding them to llm_helpers.py's existing module-level kiro_crew.acp imports would also keep the count at 5, but it rewrites those two lines, and the gate refuses an ACP import on a line the change adds; run that way, it flags both lines.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 10, 2026
Titles, the session summary and link labels call run_bg_oneliner with
no timeout. A silent backend kept each call, and its background
session, waiting until the session handle's watchdog gave up after
600 s or 1800 s. The watchdog then ends the turn with an ordinary
EVENT_COMPLETE (stop_reason stale_recover, or timeout at the turn
ceiling), and run_bg_oneliner returned the partial text as the
answer, so a cut-off title was saved. Identical link-label requests
each started their own call.

run_bg_oneliner raises AcpTimeoutError when a turn ends with
STOP_REASON_TIMEOUT (new) or STOP_REASON_STALE_RECOVER, so the
caller's failure path runs. The title and link-label calls pass a
30 s timeout and the summary 60 s. The link-label route shares one
running call among identical requests, at most 8 link sets at once;
its key and the shared call hold only the url and context cut to the
500 and 300 characters the prompt reads.
_raise_if_unfinished imported AcpTimeoutError from kiro_crew.acp.client
and the two stop reasons from kiro_crew.acp.types. That raised
llm_helpers.py's ACP-layer import count from 5 to 7 against the
shrink-only baseline of scripts/check_agent_sdk_boundary.py.

kiro_crew.agent_sdk.drivers.acp_vocab, the module that already gives
application code the stop classes and the session-start timeout, now
also exports AcpTimeoutError, STOP_REASON_STALE_RECOVER and
STOP_REASON_TIMEOUT, and _raise_if_unfinished imports them from there,
still at call time. The count is back at 5. They are the same objects,
so nothing else changes.
@javenciu
javenciu force-pushed the fix/background-oneliner-calls-are-bounded branch from aa9c49f to 9f647c0 Compare October 11, 2026 05:28
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 11, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR gives the title (30 s), session summary (60 s) and link-label (30 s) background calls a timeout, makes run_bg_oneliner raise a non-transient AcpTimeoutError when a turn ends with timeout or stale_recover instead of keeping the cut-off text as the answer, and shares one running link-label call among identical requests (bounded keys, at most 8 in flight). That fixes both reported root causes: an unbounded wait holding a background session, and a truncated title being saved. I read the full diff at head 9f647c0 and checked every one of the 15 run_bg_oneliner callers: each already handles an exception from the call (most already pass a timeout and catch Exception), AcpTimeoutError is an AcpError with no rejected_model, so the rejected-model fallback re-raises it rather than retrying, and the poisoned-conversation canary treats it as "no discard", which is the safe side. The in-flight map is shielded so one request leaving does not cancel the call for the others, its entry is removed by a done-callback however the call ends, and its keys are cut to 800 characters per link, so a large request body cannot grow it. The tests fail on main for the behavior and pass on the branch. Two notes for the author that do not block: the First Principles CONCERNS (use classify_stop_reason, the server dedupe repeats react-query's) still needs a disposition, and since useChatNavigation caches labels with staleTime: Infinity, a request refused by the 8-entry cap or the new timeout keeps raw-URL chips until reload, as a model error already does today. — crew-pr-reviewer (deep re-check)

@iamwhatever
iamwhatever enabled auto-merge (squash) October 11, 2026 18:07
@iamwhatever
iamwhatever merged commit a7d14c1 into kirodotdev:main Oct 11, 2026
109 of 117 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants