Repository navigation
docs(rfc): dashboard chat document attachments as a text sidecar - #18681
Conversation
First Principles Review (Opus 5.5, fork) — ⏭️ skippedRevision |
UX Review (Opus 5.5, fork) — ⏭️ skippedRevision |
Design Review (Opus 5.5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Check whether " [DESIGN-REVIEWED] 85748b5 Description read[DESCRIPTION-READ] b4377b59e72fca3d199160e284b7dbbf721035e1b47cf91edbe0634916299970 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 |
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings that block the merge. FINDING — docs/request-for-change/rfc-chat-document-attachments.md:218 — The PDF unit count is taken "from the segment labels". [OPUS-REVIEWED] 85748b5 |
244ba5d to
8fccec6
Compare
|
Rebased: main moved in |
8fccec6 to
c1417a0
Compare
|
Rebased: main moved in |
c1417a0 to
512e626
Compare
|
Rebased: main moved in |
Add the RFC that closes the parity gap between the dashboard and the eight messaging channels: a .pdf/.docx/.pptx attached in dashboard chat is extracted once at upload time into a redacted <upload>.txt sidecar, and build_prompt_blocks appends a [document text: <sidecar>, N pages] note to the outgoing prompt so the agent can read it with its ordinary read tool. The persisted [attached_file N] marker contract is unchanged. Register the document in the README index and audit ledger. Tracks kirodotdev#14570.
512e626 to
85748b5
Compare
|
Rebased: the previous head |
iamwhatever
left a comment
There was a problem hiding this comment.
This docs-only PR adds a draft RFC (and its README row) for issue #14570: at upload time the dashboard extracts .pdf/.docx/.pptx text into a redacted 0600 <upload>.txt sidecar, and the prompt builder appends a [document text: <path>, N pages] note so the agent can use read instead of a shell call that needs approval. It goes at the real gap (the dashboard is the only channel that does not convert documents) and keeps the [attached_file N] grammar and its three pinned readers unchanged by rewriting the outgoing prompt only, as the image pass already does. I read the design and security sections looking for holes: the prompt-side note is gated on containment under the uploads root before any stat, reads a 256-byte header through the no-follow bounded reader, admits only a ^\d+ (pages|slides)$ count, and escapes a user-typed [document text: marker. Sidecars are cleaned up with their request on refusal, PDF extraction runs out of process under one 10 s deadline shared by the whole request, and redaction runs before truncation, so the design does not open an injection, path or resource-exhaustion route that I could find. The status stays draft pending maintainer acceptance, which is the right gate for the product calls it records; the AI lane passed and no change request is open. — crew-pr-reviewer (deep re-check)
…odotdev#14570) Dashboard chat attachments reached the agent as a bare upload path while eight messaging channels already extracted and inlined document text. This closes the parity gap: each uploaded .pdf/.docx/.pptx named in the turn's meta.files is read once through PinnedDirectory.read_bytes on uploads/, extracted off the loop under one 30 s deadline shared by the request's files, and added to request_prefix_context as a [Document: name] block in the same shape ingest_attachments uses. The persisted row, the [attached_file N] marker and the UI are unchanged. Design: docs/request-for-change/rfc-chat-document-attachments.md (kirodotdev#18681). Revival of kirodotdev#17142 (closed unmerged on a merge conflict) onto current main: - The hook moved with the runner split: it lives in chat_turn/turn_dispatch_gates._turn_dispatch_prep after the self-change undo block, gated on _sends_prompt as the neighbouring blocks are. - PinnedDirectory.read_bytes is added in platform_compat_links, where the class now lives; the platform_compat facade re-exports it. - The doc_parser._docx_paragraph_texts single-pass walk is dropped: main's _extract_docx now delegates to doc_blocks.docx_text, whose block walk already visits each element once, so that part and its tests are superseded. - The two runner tests join test_chat_runner_coverage_turn_start.py and patch kiro_crew.dashboard.attachment_documents, the module the lazy import in the hook resolves. - attachments._clean_text now returns (body, whole) so the channels can hand over a whole-text copy of a cut document; the dashboard keeps the upload on disk and takes only the capped body. The cap test pins the truncation marker's shape, not its wording. Original author preserved; cherry-picked from 25a90e2.
Problem / Motivation
Goal: Record the design decision for making a
.pdf/.docx/.pptxattached in dashboard chat readable by the agent, so the implementation PRs for #14570 can be reviewed against a decision on main.Today a document attached in the dashboard reaches the agent as a bare path to bytes its
readtool cannot decode. The only route is a shell call topdftotext, which raises a tool-approval prompt; #14570 records three expired prompts before a two-page PDF was read. Crew Captain's triage asked for a maintainer design sign-off throughdocs/request-for-change/before any code changes.Why it matters
Every other channel (Slack, Discord, Telegram, Webex, Teams, WhatsApp, WeCom, Weixin) already extracts and inlines document text through
ingest_attachments. The dashboard is the one surface where this does not work, and the one where the file is already on local disk. Without the decision on main, an implementation PR's First Principles lane blocks because it changes what every dashboard prompt carrying a document says to the agent.Not a goal
[attached_file N]marker; the RFC leaves that three-site contract alone.doc_parser._extract_pdf->extract_pdf_segments); the RFC records it so a separate issue can cite it.What changed (motivation → approach → change)
docs/request-for-change/rfc-chat-document-attachments.mddraft, verified against main at8c6e7eba90docs/request-for-change/README.mdNothing changes for a user when this merges; the PR ships the design record only. The RFC proposes that
api_upload_fileextract a document's text once, at upload time, into a redacted<upload>.txtsidecar beside the file, and thatbuild_prompt_blocksappend[document text: <sidecar>, N pages]to the outgoing prompt only. The agent then reads the sidecar with its ordinaryreadtool. Persisted rows and the three marker readers see nothing new.It picks sync extraction with a 10 s deadline over a background job, and a sidecar over inline text, and says why in its Alternatives section. It also corrects four claims in the issue text that do not match the code, and it leads with the finding that the product question in the triage was already answered when the eight channels shipped.
Acceptance is requested from a maintainer; the status flips to
acceptedwhen one records it in the document's §11.Backwards compatibility
Compatible: documentation only; no runtime behavior changes.
Removes nothing: the diff adds one file and two lines to an index.
Tests
N/A — no code.
scripts/docs_lint.py,scripts/docs-lint.shandscripts/check_brand_name.pypass locally on the diff.Manual verification
Every symbol the RFC cites was checked against a clone of main at
decba819400eand re-read at8c6e7eba90, where none of the cited files had changed.Related Issues
Related: #14570 (this PR records the design; it does not close the issue)
no linked issue: the RFC is the design record for #14570, which closes when the implementation lands.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)