Skip to content

docs(rfc): dashboard chat document attachments as a text sidecar - #18681

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
kamleshnanda:docs/rfc-chat-document-attachments
Oct 13, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
kamleshnanda:docs/rfc-chat-document-attachments

Conversation

@kamleshnanda

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record the design decision for making a .pdf/.docx/.pptx attached 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 read tool cannot decode. The only route is a shell call to pdftotext, 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 through docs/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

  • No code change. This PR adds a document and its README index row only.
  • Not changing the persisted [attached_file N] marker; the RFC leaves that three-site contract alone.
  • Not implementing Phase D (doc_parser._extract_pdf -> extract_pdf_segments); the RFC records it so a separate issue can cite it.

What changed (motivation → approach → change)

Piece What it is
docs/request-for-change/rfc-chat-document-attachments.md New RFC, status draft, verified against main at 8c6e7eba90
docs/request-for-change/README.md Index row for the RFC and its audit-ledger sentence

Nothing changes for a user when this merges; the PR ships the design record only. The RFC proposes that api_upload_file extract a document's text once, at upload time, into a redacted <upload>.txt sidecar beside the file, and that build_prompt_blocks append [document text: <sidecar>, N pages] to the outgoing prompt only. The agent then reads the sidecar with its ordinary read tool. 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 accepted when 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.sh and scripts/check_brand_name.py pass locally on the diff.

Manual verification

Every symbol the RFC cites was checked against a clone of main at decba819400e and re-read at 8c6e7eba90, 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

  • 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

@kamleshnanda
kamleshnanda requested review from a team and KiroCrewCaptain as code owners October 10, 2026 00:32
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed 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

First Principles Review (Opus 5.5, fork) — ⏭️ skipped

Revision 85748b56f1fc148e80dd72d05fc674f82fc11e85 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

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

Revision 85748b56f1fc148e80dd72d05fc674f82fc11e85 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 85748b56f1fc148e80dd72d05fc674f82fc11e85 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 "read on the sidecar raises no approval prompt" holds for every selectable agent.acp_backend, not just kiro-cli. Phase A's exit criteria should run that check once per backend.

[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 .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

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] 85748b5

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No 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". pdf_extract.py:74-75 says segments are "one per page that yielded text" and PdfExtraction.pages "counts every page the child opened". So a 10-page PDF with text on 3 pages would be announced as 3 pages. Separately, §5.1 step 4 writes "no sidecar" when the text is empty, so a fully scanned PDF never gets the "PDF sidecar" that §5.4 / Phase C start from, and Phase C's own exit criterion ("A scanned 3-page PDF yields <dest>.pages/page-001..003.png") can never be met. → Fix: take the count and the Phase C per-page average from PdfExtraction.pages, and have Phase C trigger on an empty .failed result (or write a sidecar for an empty extraction).

[OPUS-REVIEWED] 85748b5

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Oct 10, 2026
@kamleshnanda
kamleshnanda force-pushed the docs/rfc-chat-document-attachments branch from 244ba5d to 8fccec6 Compare October 11, 2026 02:44
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 11, 2026
@kamleshnanda

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/request-for-change/README.md since this head went green (adfd71b8a27e -> 52f909caa817); the ledger-paragraph conflict was resolved by keeping main's text and re-appending this RFC's sentence. The two cited files that changed on main (chat_title.py, handlers/files.py) still carry every symbol the RFC names. CI re-running on 8fccec6cdf81. The previous head's one red, test/test_memory_admission_queue.py::test_message_queued_behind_a_refused_turn_runs_once_preparation_finishes (KeyError: 'queued' beside a TimeoutError, 1 of 23,990), is untouched by this docs-only diff.

@kamleshnanda
kamleshnanda force-pushed the docs/rfc-chat-document-attachments branch from 8fccec6 to c1417a0 Compare October 12, 2026 17:36
@kamleshnanda

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/request-for-change/README.md since this head went green (52f909caa817 -> d866dd260779, 304+ commits); the ledger-paragraph and index-header conflict was resolved by keeping main's text and re-appending this RFC's sentence and row. Re-read the cited files at 2e8831ea52: one fact moved, the upload cap. #18617 replaced the fixed _MAX_UPLOAD_BYTES with the configurable upload_max_bytes() (dashboard/upload_limits.py, default 100 MB), so §2.1 now cites that seam and the audit stamp is updated. No design change. Head c1417a00c011.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 12, 2026
@kamleshnanda
kamleshnanda force-pushed the docs/rfc-chat-document-attachments branch from c1417a0 to 512e626 Compare October 12, 2026 18:44
@kamleshnanda

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/request-for-change/README.md since this head went green (d866dd260779 -> 63c155a582c7, 10 commits); the ledger-paragraph conflict was resolved by keeping main's text and re-appending this RFC's sentence. No cited source file changed, so the 2e8831ea52 reading stands. Head 512e6266c54c. The red backend shards on the previous head were the main-wide effort_pendings NameError in mcp_tools/spawn.py, not this diff.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 12, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 12, 2026
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.
@kamleshnanda
kamleshnanda force-pushed the docs/rfc-chat-document-attachments branch from 512e626 to 85748b5 Compare October 12, 2026 20:51
@kamleshnanda

Copy link
Copy Markdown
Contributor Author

Rebased: the previous head 512e6266c54c sat on 63c155a582c7, whose own main CI run failed (test_wait_discipline_ratchet flagged two fixed waits #19259 added; Coverage Gate then failed closed). #19495 (65df088e393c) migrated those waits and main is green there, so this head is rebased onto it: 63c155a582c7 -> 65df088e393c, 5 commits, no overlap with this diff and no cited source file changed, so the 2e8831ea52 reading stands. The two red Windows shards were a WinError 32 file-lock in test_dashboard_server_coverage and the same ratchet. Head 85748b56f1fc. Review lanes on 512e6266c54c were Design PASS, GPT and Opus no blocking findings; the diff is unchanged.

@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 12, 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 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)

@iamwhatever
iamwhatever enabled auto-merge (squash) October 13, 2026 00:01
@iamwhatever
iamwhatever merged commit d0386ea into kirodotdev:main Oct 13, 2026
104 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 13, 2026
kamleshnanda pushed a commit to kamleshnanda/KiroCrew that referenced this pull request Nov 13, 2026
…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.
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.

3 participants