Repository navigation
feat(app-sdk): make the chatembed poll read incrementally - #20917
Conversation
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Run one live turn in an embed and check that streamed text and an in-place approval update appear without a stale row. The PR says this was never tried against a gateway. [UX-REVIEWED] 4f100d8 Description read[DESCRIPTION-READ] fdab2528afd3fe7017e1e67c36a9b39df04c5a01b8890676af71f77545e5aed4 That sha256 names everything this verdict read: the PR description, plus the 3 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) — ✅ PASSDesign-level review of Design-Verdict: PASS Have a maintainer confirm that the #8651 standalone-publish gate is met. That RFC ruling comes along in this poll PR and is not part of the poll change. [DESIGN-REVIEWED] 4f100d8 Description read[DESCRIPTION-READ] e28cd7d86577a14b8d78125c0e07ab23fa47a68f498d45b1bb8ec3e0eddbce16 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) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The poll change earns its place. A second, unrelated decision rides along with it: the RFC's ratified standalone-publish gate is marked met inside a polling PR. Not justified as shipped
What this change shipsInventory (7 items) — 6 justifiedIntent: an app's embedded chat stays current while downloading only the rows that changed. This is an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 4f100d8 Description read[DESCRIPTION-READ] 18d509d80d399498a275cd8ff09ef4fd1a2592afff064497dfce114aed96aa12 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: |
|
Dispositions for the review lanes on 69811c3, addressed in 5db6c73:
|
ChatEmbed re-read its whole bounded page (200 rows) every second while a turn ran and every five seconds idle. Slot detail now issues a cursor on request (cursor=1): the page's first and last row indices and a hash of the rendered rows before the last one. Echoing it back answers only the rows from the cursor on, marked delta, or the full page when any earlier row renders differently (an in-place edit, a rewind, a rotation, a forged digest). The embed splices a delta onto the page it holds and reads the page whole when a delta does not fit. The cursor was chosen over the WebSocket stream: the embed keeps its one scoped read, the stale-poll notice and the load-earlier bar, and needs neither a store-free copy of the chat frame reducer nor an event grant from its host app. A gateway without the cursor keeps serving plain pages. The RFC's standalone-publish gate is marked met: #8651 closed as delivered, since ChatEmbed already mounts without the store. Refs #19994
5db6c73 to
e1cb822
Compare
e1cb822 to
6a85a76
Compare
|
Rebased onto main e492fda as asked (range-diff showed both commits unchanged). After that, CodeQL raised a high alert on e1cb822: On e1cb822 the Opus and GPT lanes failed to publish ( |
A cursor read composed the page back to the held span's start so it could check it, then rendered every composed row: about two pages per poll where one plus the new rows is enough. Only rows from the older of the span start and the new window start are rendered now. The span digest hashed rendered display text, which can carry what redaction was built to find. It is now built from each row's render-memo identity: a keyed digest of the stored row plus the redaction context, the same thing the memo trusts to mean "renders the same". Rows with no such identity (a streaming chunk, an OAuth row, anything in an owner-view scope) issue no cursor over them. Each row is serialized once and both its render and its identity come from that snapshot, so an edit the event loop makes mid-render cannot certify a stale row. The span ceiling reuses SLOT_DETAIL_MAX_LIMIT instead of a second constant, the transcript contract test follows the read path into embedIncrementalRead, and the RFC marks its 2026-09-05 host-only decision as superseded and links the #8651 closing comment. Refs #19994
6a85a76 to
4f100d8
Compare
|
Dispositions for 6a85a76, addressed on 4f100d8:
|
|
Hold for a human reviewer and a maintainer decision. Reviewed head: 4f100d8. Blockers:
The cursor design is sound on reading: the digest is keyed, bound to position and capped by — crew-pr-reviewer (r105) |
Problem / Motivation
Goal: An app's embedded chat stays current by fetching only the rows that changed, instead of re-downloading its whole 200-row page every second.
ChatEmbedpollsGET /api/chat/slots/{slot}?limit=200every 1 s while a turn runs and every 5 s idle. Each poll sends back the full page, so a running turn that adds one streamed sentence still moves 200 rendered rows over the wire, and the embed parses and diffs all of them. The RFC's P5-f row and #19994's phase P-d record this as the open item.Why it matters
Every app that mounts
ChatEmbed(spec-builder, ops-mission-control, third-party apps) pays this per second per open embed. On a long session the page is the 200 largest-recent rows, so the cost tracks the size of history rather than the size of what changed.Not a goal
What changed (motivation → approach → change)
Choice: since-cursor over the WebSocket stream. The WebSocket route would need a store-free copy of the dashboard's chat frame reducer (chunks, tool rows, in-place
chat_message_update, approvals, queue frames), it only delivers for slots the app owns unless the host grants aslots:*scope, and the defaultsubscribeFnis a no-op. The cursor keeps the embed's single read through the app's scopedapi, soallowedApiPaths, the stall/back-off logic and the load-earlier widening all stay as they are.Why a plain index cursor is not enough. Rows are edited in place far from the tail (
_mark_permission_resolved, card patches inchat_cards.py, MCP sign-in rows, steer meta). A cursor of "rows after N" would miss those edits. So the cursor carries a digest of the rows the reader already holds, and the server checks it.Backend (
src/kiro_crew/dashboard/slot_detail_delta.py, wired intoapi_chat_slot_detail):?limit=L&cursor=1returns the same page pluscursor: {from, since, digest}: the first row's index, the last row's index, and a digest of the rows in[from, since). The digest is built from each row's render-memo identity (wire_render.prepare_message_rows: a keyed digest of the stored row plus the redaction context and running flag), never from display text. Each row is serialized once and both its fragment and its identity come from that snapshot. Rows with no identity (a streaming chunk, an OAuth row, any row in an owner-view scope) issue no cursor over them. The last row (the folded streaming row) is always outside the span.?limit=L&from=F&since=S&digest=Dcomposes the page reaching back toF, and compares the digest of[F, S)again. Equal: only rows fromSon, plusdelta: {from, since}andnext_before= new window start. Not equal (in-place edit, rewind, rotation, changed redaction context, forged digest, span wider than a page): the full page, nodelta.wire_render.prepare_message_rowsreturns per-row rendered text and identities;prepare_messages_jsonjoins the text, same bytes as before.Fso the span can be checked, but only rows from the older ofFand the new window start are rendered (render_from): about one page plus the rows new since the last poll.SLOT_DETAIL_MAX_LIMIT, the handler's own page ceiling.cursor+beforeare400 invalid_query_params. Cursor reads always take the paged route.Frontend (
website/src/app-sdk/embedIncrementalRead.ts,ChatEmbed.tsx): the query function reads the held page from the query cache, echoes its cursor, and splices adeltaonto the held rows (dropping rows before the new window start). Adeltathat does not answer the cursor sent, or does not fit, triggers one full re-read. A response with nodeltareplaces the page, as today.RFC (
docs/request-for-change/rfc-chat-core-extraction.md): §4.1's standalone-publish gate said to wait on #8651. #8651 closed as delivered on 2026-10-11 (ChatEmbedmounts without the store; the RFC links the closing comment), so the gate is marked met and the 2026-09-05 host-only decision is marked superseded forChatEmbed; the note thatChatInputitself is still store-bound stays. This correction was asked for in the same dispatch as the poll change (tracking #19994). The #8651 row is updated, and the P5-f row is split so the embed slice reads "in review" and the ChatPage/ChatPane slices keep their own status.Spec:
docs/system-specs/modules/history.mddocuments the cursor contract next to the paginated slot-detail section.Backwards compatibility
Compatible: the cursor is opt-in. A read without
cursor=1orfrom/since/digestis served exactly as before (same fields, same order). An embed talking to a gateway without this change never gets acursorand keeps full reads. The request still goes to/api/chat/slots/{slot}, so the/api/chatgrant still covers it.Removes nothing: only new optional query parameters and response fields are added.
Tests
test/test_slot_detail_delta.py(backend, 24): row identities follow the stored row, OAuth/chunk rows and owner-view rows carry none, a row without identity inside the span issues no cursor, identities are length-framed in the digest; an in-place edit during render cannot pair the old fragment with the new identity (memo and non-memo paths); assistant, markdown, link and tool rows hash the same across polls so a running turn still gets deltas; a cursor read renders only the rows it hashes or serves (12, not the 19 composed); acursor=1read serves the same rows as a plain read; an echoed cursor gets only the re-sent last row plus new rows and the slid window start; a row edited in place inside the span returns the full page; a forged digest returns the full page; cursor withoutlimitstays bounded; malformed cursors andcursor+beforeare 400;plan_pageedge cases (misaligned rows, a dropped row inside vs at the end of the span, empty session, cursor behind the composed page, position-bound digest).website/src/test/embedIncrementalRead.test.ts(6): path building, cursor validation (rejects a digest that would inject query text), splice arithmetic, refusal of deltas it cannot place.website/src/test/ChatEmbed.boundedPoll.test.tsx(3 new): the embed echoes the held cursor and showsheld-kept + deltarows; a full page replaces; a mismatched delta triggers a full re-read.test_a_row_edited_in_place_falls_back_to_the_full_pageandtest_a_forged_digest_is_a_full_page; never applying a delta reddenstest_echoed_cursor_gets_only_the_new_rows; rendering from the composed page start reddenstest_a_cursor_read_renders_about_one_page([10, 19] != [10, 12]); ignoring the held cursor inChatEmbedreddens "echoes the held cursor and splices…".ChatEmbed.boundedPoll.test.tsxandChatEmbed.test.tsx(first read now ends&cursor=1);chatCoreTranscript.contract.test.tsnow pins the bounded path insideembedIncrementalRead.ts.Manual verification
Not run against a live gateway. Covered by the handler tests above, which drive the real aiohttp route. Local gate: black/isort/flake8 clean on touched files, comment-history and brand gates pass,
tsc -p tsconfig.app.jsonclean, 322 ChatEmbed/app-sdk/app vitest cases pass.local-gate.pybackend step reported 97 failures, none in slot-detail or chat tests; the same files (test_file_explorer_app.py,test_onboarding_import_refactor_contract.py,test_perf_boot_path.py,test_design_tweak_backend.py,test_cli.py) fail the same way on a cleanorigin/mainworktree on this host.mypyreports 3 errors inwecom/client.py, untouched here.Screenshots / video
Why no screenshot: the embed renders the same rows as before; only how the poll fetches them changed.
Related Issues
Refs #19994 (phase P-d). Overlap with open PRs, checked with
git merge-treeagainst this head: #19898, #19887, #19903 and #20178 touchChatEmbed.tsx(and #19898slot_detail.py, #20178 the RFC) and all merge cleanly; #19890 and #19879 share no files. #19879's contract page still describes the poll correctly (same path and cadence).Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.